3.2 ORPC Base Definitions

There are several fundamental data types and structures on which the COM network protocol is built. These types are shown here in standard C header format.

[
    uuid(99fcfe60-5260-101b-bbcb-00aa0021347a),
    pointer_default(unique)
]
interface ObjectRpcBaseTypes
{
    ////////////////////////////////////////////////////////////
    //
    //  Identifier Definitions
    //
    ////////////////////////////////////////////////////////////

    typedef unsigned hyper ID;
    typedef ID      MID;        // Machine Identifier
    typedef ID      OXID;       // Object Exporter Identifier
    typedef ID      OID;        // Object Identifer
    typedef ID      SETID;      // Ping Set Identifier
    typedef GUID    IPID;       // Interface Pointer Identifier
    typedef GUID    CID;        // Causality Identifier

    typedef const IPID &REFIPID;
    typedef REFGUID REFIPID;

    //////////////////////////////////////////////////////////////////
    //
    //  ORPC Call Packet Format
    //
    //////////////////////////////////////////////////////////////////

    // COM_MINOR_VERSION = 1   (NT4.0, SP1, SP2, DCOM95).
    //      - Initial Release
    //      - Must be used when talking to downlevel machines, including
    //        on Remote Activation calls.
    // COM_MINOR_VERSION = 2   (NT4.0 SP3 and beyond).
    //      - Added ResolveOxid2 to IObjectExporter to retrieve the
    //        COM version number of the server. Passed to the NDR engine
    //        to fix fatal endian-ness flaw in the way OLEAUTOMATION marshals
    //        BSTRS. Previous way used trailing padding, which is not NDR
    //        compatible. See Bug# 69189.
    // COM_MINOR_VERSION = 3   (NT4.0 SP4 and DCOM95 builds 1018 and beyond)
    //      - OLEAUT32 added two new types to the SAFEARRAY, but SAFEARRAY
    //        previously included the "default" keyword, which prevented
    //        downlevel NDR engines from correctly handling any extensions.
    //        Machines with version >=5.3 don't use "default" and will
    //        gracefully handle future extensions to SAFEARRAY.

    // old constants (for convenience)
    const unsigned short COM_MINOR_VERSION_1 = 1;
    const unsigned short COM_MINOR_VERSION_2 = 2;

    // current version
    const unsigned short COM_MAJOR_VERSION = 5;
    const unsigned short COM_MINOR_VERSION = 3;

    // Component Object Model version number
    typedef struct tagCOMVERSION
    {
        unsigned short MajorVersion;    // Major version number
        unsigned short MinorVersion;    // Minor version number
    } COMVERSION;


    // enumeration of additional information present in the call packet.
    // Should be an enum but DCE IDL does not support sparse enumerators.

    const unsigned long ORPCF_NULL      = 0;  // no additional info in packet
    const unsigned long ORPCF_LOCAL     = 1;  // call is local to this
machine
    const unsigned long ORPCF_RESERVED1 = 2;  // reserved for local use
    const unsigned long ORPCF_RESERVED2 = 4;  // reserved for local use
    const unsigned long ORPCF_RESERVED3 = 8;  // reserved for local use
    const unsigned long ORPCF_RESERVED4 = 16; // reserved for local use

    // Extension to implicit parameters.
    typedef struct tagORPC_EXTENT
    {
        GUID                    id;          // Extension identifier.
        unsigned long           size;        // Extension size.
        [size_is((size+7)&~7)]  byte data[]; // Extension data.
    } ORPC_EXTENT;


    // Array of extensions.
    typedef struct tagORPC_EXTENT_ARRAY
    {
        unsigned long size;     // Num extents.
        unsigned long reserved; // Must be zero.
        [size_is((size+1)&~1,), unique] ORPC_EXTENT **extent; // extents
    } ORPC_EXTENT_ARRAY;


    // implicit 'this' pointer which is the first [in] parameter on
    // every ORPC call.
    typedef struct tagORPCTHIS
    {
        COMVERSION      version;    // COM version number
        unsigned long   flags;      // ORPCF flags for presence of other data
        unsigned long   reserved1;  // set to zero
        CID             cid;        // causality id of caller

        // Extensions.
        [unique] ORPC_EXTENT_ARRAY *extensions;
    } ORPCTHIS;


    // implicit 'that' pointer which is the first [out] parameter on
    // every ORPC call.
    typedef struct tagORPCTHAT
    {
        unsigned long  flags;       // ORPCF flags for presence of other data

        // Extensions.
        [unique] ORPC_EXTENT_ARRAY *extensions;
    } ORPCTHAT;


    //////////////////////////////////////////////////////////////////
    //
    //  Marshaled COM Interface Wire Format
    //
    //////////////////////////////////////////////////////////////////

    // DUALSTRINGARRAYS are the return type for arrays of network addresses,
    // arrays of endpoints and arrays of both used in many ORPC interfaces

    const unsigned short NCADG_IP_UDP   = 0x08;
    const unsigned short NCACN_IP_TCP   = 0x07;
    const unsigned short NCADG_IPX      = 0x0E;
    const unsigned short NCACN_SPX      = 0x0C;
    const unsigned short NCACN_NB_NB    = 0x12;
    const unsigned short NCACN_NB_IPX   = 0x0D;
    const unsigned short NCACN_DNET_NSP = 0x04;
    const unsigned short NCACN_HTTP     = 0xlF;
    typedef struct tagSTRINGBINDING
    {
         unsigned short wTowerId;     // Cannot be zero.
         unsigned short aNetworkAddr; // Zero terminated.
    } STRINGBINDING;

    const unsigned short COM_C_AUTHZ_NONE = 0xffff;

    typedef struct tagSECURITYBINDING
    {
        unsigned short wAuthnSvc;  // Cannot be zero.
        unsigned short wAuthzSvc;  // Must not be zero.
        unsigned short aPrincName; // Zero terminated.
    }  SECURITYBINDING;

    typedef struct tagDUALSTRINGARRAY
    {
        unsigned short wNumEntries;     // Number of entries in array.
        unsigned short wSecurityOffset; // Offset of security info.

        // The array contains two parts, a set of STRINGBINDINGs
        // and a set of SECURITYBINDINGs.  Each set is terminated by an
        // extra zero.  The shortest array contains four zeros.

        [size_is(wNumEntries)] unsigned short aStringArray[];
    } DUALSTRINGARRAY;

    // signature value for OBJREF (object reference, actually the
    // marshaled form of a COM interface).
    const unsigned long OBJREF_SIGNATURE = 0x574f454d;  // 'MEOW'

    // flag values for OBJREF
    const unsigned long OBJREF_STANDARD = 0x1;  // standard marshaled objref
    const unsigned long OBJREF_HANDLER  = 0x2;  // handler marshaled objref
    const unsigned long OBJREF_CUSTOM   = 0x4;  // custom marshaled objref

    // Flag values for a STDOBJREF (standard part of an OBJREF).
    // SORF_OXRES1 - SORF_OXRES8 are reserved for the object exporters
    // use only, object importers must ignore them and must not enforce MBZ.

    const unsigned long SORF_OXRES1     = 0x1;  // reserved for exporter
    const unsigned long SORF_OXRES2     = 0x20; // reserved for exporter

    const unsigned long SORF_OXRES3     = 0x40; // reserved for exporter
    const unsigned long SORF_OXRES4     = 0x80; // reserved for exporter
    const unsigned long SORF_OXRES5     = 0x100;// reserved for exporter
    const unsigned long SORF_OXRES6     = 0x200;// reserved for exporter
    const unsigned long SORF_OXRES7     = 0x400;// reserved for exporter
    const unsigned long SORF_OXRES8     = 0x800;// reserved for exporter

    const unsigned long SORF_NULL       = 0x0;   // convenient for
initializing SORF
    const unsigned long SORF_NOPING     = 0x1000;// Pinging is not required


    // standard object reference
    typedef struct tagSTDOBJREF
    {
        unsigned long  flags;              // STDOBJREF flags (see above)
        unsigned long  cPublicRefs;        // count of references passed
        OXID           oxid;               // oxid of server with this oid
        OID            oid;                // oid of object with this ipid
        IPID           ipid;               // ipid of Interface
    } STDOBJREF;

    // OBJREF is the format of a marshaled interface pointer.
    typedef struct tagOBJREF
    {
        unsigned long signature;           // must be OBJREF_SIGNATURE
        unsigned long flags;               // OBJREF flags (see above)
        GUID          iid;                 // interface identifier

        [switch_is(flags), switch_type(unsigned long)] union
        {
            [case(OBJREF_STANDARD)] struct
            {
                STDOBJREF       std;       // standard objref
                DUALSTRINGARRAY saResAddr; // resolver address
            } u_standard;

            [case(OBJREF_HANDLER)] struct
            {
                STDOBJREF       std;       // standard objref
                CLSID           clsid;     // Clsid of handler code
                DUALSTRINGARRAY saResAddr; // resolver address

            } u_handler;

            [case(OBJREF_CUSTOM)] struct
            {
                CLSID           clsid;     // Clsid of unmarshaling code
                unsigned long   cbExtension;// size of extension data
                unsigned long   size;      // size of data that follows
                [size_is(size), ref] byte *pData; // extension + class
specific data
            } u_custom;

        } u_objref;

    } OBJREF;

    // wire representation of a marshalled interface pointer
    typedef struct tagMInterfacePointer
    {
        ULONG           ulCntData;          // size of data
        [size_is(ulCntData)] BYTE abData[]; // data (OBJREF)
    } MInterfacePointer;

    typedef [unique] MInterfacePointer * PMInterfacePointer;
}


//////////////////////////////////////////////////////////////////