Simplify Native DLL Documentation for Use by .NET / Managed Code Authors





4.00/5 (3 votes)
Sep 13, 2007
2 min read

32542

556
An article describing how to manage the interface between native and managed code
Introduction
Do you need to manage the interface between native and managed code? Using a few simple documentation comments and this tool, you can create up-to-date documentation of your native C/C++ code, complete with C# DllImport
statements. This tool also auto-translates between C/C++ data types and C# data types.
Using the Code
This tool (DllImportDoc.exe) should be run with the current directory containing the *.C, *.CPP and *.H files that contain your autodoc comments. The generated documentation is written to DOCUMENTATION.HTML. There are three optional text files that you can also create in the same directory:
- autodoc_header.txt contains the text/HTML that DllImportDoc.exe will place at the top of DOCUMENTATION.HTML (ex. your title).
- autodoc_overview.txt contains the text/HTML that DllImportDoc.exe will place in the Overview section of DOCUMENTATION.HTML (ex. introductory paragraph).
- autodoc_footer.txt contains the text/HTML that DllImportDoc.exe will place at the end of DOCUMENTATION.HTML (ex. your copyright notices).
The autodoc comments to use in your C/C++ comments for your functions are:
@dllname
[the name of your DLL as you would like it to appear in C#DllImport
statements]@func
[function name] | [function description as you would like it to appear in HTML help]@return
[C/C++ return data type (ex.int
)] | [the significance of the return type (ex. number of matches found)]@param
[C/C++ data type] [parameter name] | [parameter description]@note
[additional notes you can provide about this function]@see
[a comma-separated see-also list of other functions that the documentation should link to (in the same file)]@area
[the general group of functionality this function belongs too (i.e. communication functions)]
Here is an example included in the SAMPLE.CPP file included in the source ZIP:
/*
@dllname: CoolNativeCode.dll
*/
WCHAR *wcTestString = "Test String!";
/****************************************************************************
@func: GetStringLength | Determines number of characters in the string
@return: uint | The number of characters
@note: A note can go here.
@see: GetStringValue
@area: Strings
***************************************************************************/
DLLEXPORT UINT GetStringLength()
{
return wcslen( wcTestString ) + 1;
}
/***************************************************************************
@func: GetStringValue | Retreives the string value.
@param: WCHAR* wcString | String buffer to receive the string
@param: UINT uiCharactersAllocated | Number of characters wcString can hold
@return: uint | number of characters copied to the string, 0 if failure
@note: If the buffer is not large enough, then 0 is returned
@see: GetStringLength
@area: Strings
***************************************************************************/
DLLEXPORT UINT GetStringValue( WCHAR *wcString, UINT uiCharactersAllocated )
{
uint uiLength = wcslen( wcTestString ) + 1;
if ( uiLength > uiCharactersAllocated )
return 0;
StringCchCopy( wcString, uiCharactersAllocated, wcTestString );
return uiLength;
}
It is also helpful to track the value and meanings of messages that can be sent from native code to managed windows. The autodoc comments to use in your C/C++ comments for your message #defines
are:
@messheader
[your title for this group of message IDs] | [your description of these types of messages]@mess
[name of your message ID] | [numberic value] | [your description of this message (i.e. what it means, what the managed code should do in response to this message)]@note
[additional notes can go here]
Here is an example included in the SAMPLE.H file included in the source ZIP:
/*
@messheader: My Messages |
These are messages that can be sent from the native
code to a Window created by managed code.
The C# enum is
public enum ShellMessage
{
DoSomething = 0x00,
DoSomethingElse
}
*/
/*
@mess: DO_SOMETHING | 0x00 | Cool message that indicates X.
@note: Notes can go here
*/
#define DO_SOMETHING 0
/*
@mess: DO_SOMETHING_ELSE| 0x01 | Message indicating that Y has happened
*/
#define DO_SOMETHING_ELSE 1
Points of Interest
The conversion between C/C++ data types and C# data types primarily takes place in PARAMETERS.CS. By default, LPGUID
will map to ref Guid
, HWND
will map to IntPtr
and anything that ends with *
(int*
) will map to an associated data type that starts with ref
(ref int
). If you would like to customize this mapping, simply update the case statement in ToManagedCode()
.
History
- December 2006: Limited Release
- September 2007: First Public Release