Advanced Mappings

SharpGenTools allows you to heavily customize the mappings from C++ to C#. This page covers all of the currently supported mappings for each element type.

All attributes referred to below are on a <map> element under the <mapping> tag in the <config> tag.

Warning

Mapping rules in <map> tags apply to all matching elements in the mapping, not just the elements from includes in the current config file. This allows users with multi-assembly mapping and config files (described in Advanced SharpGenTools Configuration Options) to reuse mapping rules without having to include unneeded files in the reused config. You can limit what elements are matched to specific include files with context rules, explained in Context Directives.

Selecting Elements

Each mapping rule has to select elements to modify. You select elements by using a specific attribute on the <map> tag (see the table below), along with a C# regular expression as the value. Do note, the start and end matchers ^ and $ are implied, so you do not need to add them to your regular expression.

To select an element, your regular expression needs to match its C++ qualified name. For enumeration items, you use the name that does not include the name of the enumeration. For methods, parameters, and fields, you use the qualified name of the parent concatenated with :: and then the name of the element. For purposes of a “parent”, the method is the parent of the parameter.

Additionally, you can prepend a # to your selector to select the immediate parent of the matched element. This is useful in mapping some COM libraries where an enumeration member is well known, but the enum name is a non-user-friendly generated name.

Mapping Tag Attribute Elements Modified Link to Specific Mapping Rules
enum Enumerations Enums
enum-item Enumeration Items Enum Items
struct Structs Structs
field Struct Fields Fields
interface Interfaces Interfaces
method Interface Methods Functions and Methods
function Non-member Functions Functions and Methods
param Parameters Parameters
element All matching elements All sections applicable
doc Documentation Links Doc Links

Context Directives

Context directives allow you to limit which includes mapping rules apply to. You can do this via the <context> tag.

To add a context for a set of mapping rules, add a <context>IncludeName</context> before the rules, and a <context-clear /> after the rules. You can add multiple <context> tags to enable rules to affect a multiple headers and only those headers.

If you have multiple headers you want to repeatedly use as a singular context, you can define a context set such as below:

<context-set id="common-context">
    <context>firstHeader</context>
    <context>secondHeader</context>
</context-set>

You can then enable this context with the context tag as follows <context>common-context</context>.

If you want to limit rules to applying to C++ elements that were generated from a macro or GUID, you need to add two context tags as shown below:

<context>myConfigId</context>
<context>myConfigId-ext</context>

Warning

Additionally, the name in the <context> tag must match case with the first time the header was included, even if the header was first included transitively via a different header. If they don’t match, the mapping rules will not affect the correct context.

General

  • name-tmp

    • Rename the element to the name given here and allow naming rules (in SharpGen Naming Rules) to still run on these elements.
    • The value here can be a C# regex replacement expression for the corresponding regex used in the selector.
  • name

    • Rename the element to the name given here and do not allow naming rules (in SharpGen Naming Rules) to still run on these elements.
    • The value here can be a C# regex replacement expression for the corresponding regex used in the selector.
  • visibility

    • Override the visibility and other modifiers of the resulting C# element. Options are listed below.
    • public
    • internal
    • protected
    • private
    • override
    • abstract
    • partial
    • static
    • const
    • virtual
    • readonly
    • sealed
  • naming

    • Override default naming rules. Options are listed below and explained in more detail in SharpGen Naming Rules

    • default

      • Use default naming rules.
    • noexpand

      • Do not expand short name rules for the name of this element.
    • underscore

      • Keep the underscores between each part of the original name if it was snake_case.

All Types

  • assembly

    • The assembly the type should be in. When specified, this requires a namespace attribute as well.
  • namespace

    • The namespace the type should be in. When specified, this requires an assembly attribute as well.

All Marshallable Elements

  • type

    • The type presented to the user in the mapping.
  • override-native-type

    • Override the native representation with the type specified in the type attribute.
  • pointer

    • Override the pointer arity of the matching C++ elements.
  • array

    • Override the array dimension of the matching C++ elements.
  • relation

    • Specify that this marshallable element is related to another marshallable element or has a constant value. See SharpGen Mapping Relations for more information.

Enums

  • flags

    • Specifies if this enumeration should be generated with the [Flags] attribute.
  • none

    • Specifies if SharpGenTools should generate a member named None with the value 0.

Enum Items

Enum items can only be configured with the General rules.

Structs

  • native

    • Force generation of native marshal type for this struct.
  • struct-to-class

    • Generate this structure as a C# class instead of a struct.
  • marshal

    • Marks this struct as having custom marshalling methods, so marshalling methods will not be generated. See SharpGen Native Marshalling for details.
  • static-marshal

  • new

    • Marks that this struct’s native structure has a custom construction method instead of the constructor. See SharpGen Native Marshalling for details.
  • marshalto

  • pack

    • Specifies the packing/alignment of the structure.

Fields

Fields can only be configured with the General and All Marshallable Elements rules.

Interfaces

Functions and Methods

  • check

    • Enable or disable automatically checking the error code. Defaults to true (enabled).
  • hresult

    • Force the error code to be returned.
  • rawptr

    • Force generation of a private overload of the method that has all array, pointer, or interface parameters as IntPtr.
  • return

    • Always return the return value of the function.
  • type
    • The user-visible return type of the element.

Rules for methods only:

  • property

    • Enable or disable automatic property generation. Defaults to true (enabled).
  • persist

    • Cache the value for the generated property getter the first time the getter is called.
  • custom-vtbl

    • Generate a private variable for the virtual method table index of the method, so it can be customized at runtime as needed.
  • offset-translate

    • Offset the virtual method table index by a this value.
  • keep-implement-public

    • If the parent interface has dual-callback set to true, then keep the implementation of this method in the default implementation public.

Rules for functions only:

  • dll

    • The expression to put in the DllImport attribute as the dll name.
  • group

Parameters

  • attribute

    • Override the attributes for this parameter. Options are below:

    • none

    • in

      • This parameter is an input parameter.
    • out

      • This parameter is an output parameter.
    • inout

      • This parameter is both an in and out parameter;
    • buffer

      • This parameter takes in an array of elements.
    • optional

      • This parameter is optional.
    • fast

      • If this parameter is an out parameter, reuse the C# interface instance for the returned value by setting the NativePointer property.
    • params

      • Use the C# params modifier on this parameter.
    • value

      • Force a C# value type to be passed by value to the generated method for this parameter even if the size is greater than 16 bytes.
  • return

    • Use this parameter as the return value of the generated C# method/function for this parameter’s parent C++ method/function.

Miscellaneous