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

• Download source - 22.2 KB

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