windows-server-2003/com/ole32/idl/public/objex.idl

//+-------------------------------------------------------------------------
//
//  Microsoft Windows
//  Copyright (C) Microsoft Corporation, 1992 - 1995.
//
//  File:      objex.idl
//
//  Synopsis:      Interface implemented by object exporters.
//
//  This is the interface that needs to be supported by hosts that export
//  objects. Only one instance of this interface can be exported by the host.
//
//  An object exporter needs to be able to:
//  1. return string bindings that can be used to talk to objects it
//     has exported
//  2. receive pings from object importers to keep the objects alive
//
//  Note that changes to this interface can effect IActivation because the
//  RemoteActivation method of IActivation includes information otherwise
//  retrieved from ResolveOxid.
//
//--------------------------------------------------------------------------
[
    uuid(99fcfec4-5260-101b-bbcb-00aa0021347a),
    pointer_default(unique)
]

interface IObjectExporter
{
    import "obase.idl";

    // Method to get the protocol sequences, string bindings and machine id
    // for an object server given its OXID.

    [idempotent] error_status_t ResolveOxid
    (
    [in]       handle_t        hRpc,
    [in]       OXID           *pOxid,
    [in]       unsigned short  cRequestedProtseqs,
    [in,  ref, size_is(cRequestedProtseqs)]
               unsigned short  arRequestedProtseqs[],
    [out, ref] DUALSTRINGARRAY **ppdsaOxidBindings,
    [out, ref] IPID            *pipidRemUnknown,
    [out, ref] DWORD           *pAuthnHint
    );

    // Simple ping is used to ping a Set. Client machines use this to inform
    // the object exporter that it is still using the members of the set.
    // Returns S_TRUE if the SetId is known by the object exporter,
    // S_FALSE if not.

    [idempotent] error_status_t SimplePing
    (
    [in]  handle_t  hRpc,
    [in]  SETID    *pSetId  // Must not be zero
    );

    // Complex ping is used to create sets of OIDs to ping. The whole set
    // can subsequently be pinged using SimplePing, thus reducing network
    // traffic.

    [idempotent] error_status_t ComplexPing
    (
    [in]       handle_t        hRpc,
    [in, out]  SETID          *pSetId,  // In of 0 on first call for new set.
    [in]       unsigned short  SequenceNum,
    [in]       unsigned short  cAddToSet,
    [in]       unsigned short  cDelFromSet,
    [in, unique, size_is(cAddToSet)]   OID AddToSet[],    // add these OIDs to the set
    [in, unique, size_is(cDelFromSet)] OID DelFromSet[],  // remove these OIDs from the set
    [out]      unsigned short *pPingBackoffFactor         // 2^factor = multipler
    );

    // In some cases the client maybe unsure that a particular binding will
    // reach the server.  (For example, when the oxid bindings have more then
    // one TCP/IP binding)  This call can be used to validate the binding
    // from the client.

    [idempotent] error_status_t ServerAlive
    (
    [in]       handle_t        hRpc
    );

    // Method to get the protocol sequences, string bindings, RemoteUnknown IPID,
    // and COM version for an object server given its OXID. Supported by DCOM
    // version 5.2 and above.

    [idempotent] error_status_t ResolveOxid2
    (
    [in]       handle_t        hRpc,
    [in]       OXID           *pOxid,
    [in]       unsigned short  cRequestedProtseqs,
    [in,  ref, size_is(cRequestedProtseqs)]
               unsigned short  arRequestedProtseqs[],
    [out, ref] DUALSTRINGARRAY **ppdsaOxidBindings,
    [out, ref] IPID            *pipidRemUnknown,
    [out, ref] DWORD           *pAuthnHint,
    [out, ref] COMVERSION      *pComVersion
    );

    // In some cases the client maybe unsure that a particular binding will
    // reach the server.  (For example, when the oxid bindings have more then
    // one TCP/IP binding)  This call can be used to validate the binding
    // from the client.  During activation the client does not know what
    // security providers the server supports.  Return those as well.

    [idempotent] error_status_t ServerAlive2
    (
    [in]       handle_t        hRpc,
    [out, ref] COMVERSION      *pComVersion,
    [out, ref] DUALSTRINGARRAY **ppdsaOrBindings,
    [out, ref] DWORD           *pReserved
    );

}