Click here to Skip to main content
Click here to Skip to main content

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

, 13 Sep 2007
Rate this:
Please Sign up or sign in to vote.
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

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

Jason Nottingham
Web Developer
United States United States
No Biography provided

Comments and Discussions

 
-- There are no messages in this forum --
| Advertise | Privacy | Terms of Use | Mobile
Web01 | 2.8.1411019.1 | Last Updated 13 Sep 2007
Article Copyright 2007 by Jason Nottingham
Everything else Copyright © CodeProject, 1999-2014
Layout: fixed | fluid