windows-nt/Source/XPSP1/NT/com/rpc/runtime/rtifs/epmp.idl

/*++

Copyright (C) Microsoft Corporation, 1991 - 1999

Module Name:

    epmp.idl

Abstract:

    This file specifies the interface to the endpoint mapper

Author:

    Bharat Shah  (barats) 2-11-92

Revision History:

    barats      03-13-92    Changed to new spec.
    barats      05-10-92    Midl related bugbug removed
    mariogo     06-08-94    Changed to full pointers.
    mariogo     04-24-96    Added local interface for local runtime
                            <-> rpcss calls.
    gopalp      06-03-97    Added code to cleanup stale EP Mapper entries.

--*/

#ifdef WIN
#define __RPC_FAR __far
#else
#define __RPC_FAR
#endif




//
// EPMP Interface.
//

[
    uuid(e1af8308-5d1f-11c9-91a4-08002b14a0fa), version(3.0),
    pointer_default(ptr)
]


interface epmp

{
import "nbase.idl";

//
//    Well known endpoint mapper constants
//

const unsigned32 ep_max_annotation_size     = 64;
const unsigned32 EP_S_SUCCESS               = 0x00000000;
const unsigned32 EP_S_CANT_PERFORM_OP       = 0x16c9a0cd;
const unsigned32 EP_S_DATABASE_INVALID      = 0x16c9a0cf;
const unsigned32 EP_S_CANT_CREATE           = 0x16c9a0d0;
const unsigned32 EP_S_CANT_ACCESS           = 0x16c9a0d1;
const unsigned32 EP_S_BAD_ENTRY             = 0x16c9a0d3;
const unsigned32 EP_S_UPDATA_FAILED         = 0x16c9a0d4;
const unsigned32 EP_S_NOT_REGISTERED        = 0x16c9a0d6;
const unsigned32 EP_S_SERVER_UNAVAILABLE    = 0x16c9a0d7;


//
// User Defind Types
//

typedef unsigned long ulong;

typedef unsigned32 error_status;

typedef [context_handle] void * ept_lookup_handle_t;
typedef [context_handle] void * ept_cleanup_handle_t;

#define ep_max_annotation_size 64

typedef struct _twr_t {
    unsigned32 tower_length;
    [size_is(tower_length)]
    byte tower_octet_string[];
} twr_t, *twr_p_t;

#ifdef _CLIENT_PASS_
typedef [unique] twr_t *TWR_P_T;
#else
typedef [ptr] twr_t *TWR_P_T;
#endif

typedef struct {
    UUID object;
    twr_p_t tower;
    [string] char annotation[ep_max_annotation_size];
} ept_entry_t;


typedef [ptr] ept_entry_t * ept_entry_p_t;


typedef struct _I_Tower {
    TWR_P_T Tower;
} I_Tower;



//
//    Interface Exported Methods
//

void
ept_insert(
    [in] handle_t hEpMapper,
    [in] unsigned32 num_ents,
    [in, size_is(num_ents)] ept_entry_t entries[],
    [in] unsigned long replace,
    [out] error_status *status
    );

void
ept_delete (
    [in] handle_t hEpMapper,
    [in] unsigned32 num_ents,
    [in, size_is(num_ents)] ept_entry_t entries[],
    [out] error_status *status
    );

void
ept_lookup (
    [in] handle_t hEpMapper,
    [in] unsigned32 inquiry_type,
    [in, ptr] UUID   * object,
    [in, ptr] RPC_IF_ID * Ifid,
    [in] unsigned32 vers_option,
    [in, out] ept_lookup_handle_t *entry_handle,
    [in] unsigned32 max_ents,
    [out] unsigned32 *num_ents,
    [out, length_is(*num_ents), size_is(max_ents)] ept_entry_t entries[],
    [out] error_status *status
    );

#ifdef _CLIENT_PASS_

void __RPC_FAR
ept_map (
    [in] handle_t hEpMapper,
    [in, ptr] UUID * obj,
    [in, ptr] twr_p_t map_tower,
    [in, out] ept_lookup_handle_t  *entry_handle,
    [in] unsigned32 max_towers,
    [out] unsigned32 *num_towers,
    [out,size_is(max_towers),length_is(*num_towers)] TWR_P_T *ITowers,
    [out] error_status *status
    );

#elif _SERVER_PASS_

void __RPC_FAR
ept_map (
    [in] handle_t hEpMapper,
    [in, ptr] UUID * obj,
    [in, ptr] twr_p_t map_tower,
    [in, out] ept_lookup_handle_t  *entry_handle,
    [in] unsigned32 max_towers,
    [out] unsigned32 *num_towers,
    [out,size_is(max_towers),length_is(*num_towers)] TWR_P_T *ITowers,
    [out] error_status *status
    );

#else
#error must define either _CLIENT_PASS_ or _SERVER_PASS_ (for Win95 and NT 3.1 compatibility)
#endif

void
ept_lookup_handle_free (
    [in] handle_t h,
    [in, out] ept_lookup_handle_t *entry_handle,
    [out] error_status *status
    );

void
ept_inq_object (
    [in] handle_t hEpMapper,
    [in] UUID *ept_object,
    [out] error_status *status
    );

void
ept_mgmt_delete (
    [in] handle_t hEpMapper,
    [in] boolean32 object_speced,
    [in, ptr] UUID * object,
    [in, ptr] twr_p_t tower,
    [out] error_status *status
    );

} // interface epmp




//
// LOCALEPMP Interface.
//


#if !defined(MAC) && !defined(MPPC)
[
    uuid(0b0a6584-9e0f-11cf-a3cf-00805f68cb1b),
    version(1.1)
]
interface localepmp
{

    typedef [context_handle] void *HPROCESS;

    //
    // Must be called to call the local endpoint mapper at all.
    //
    error_status_t
    OpenEndpointMapper([in]  handle_t hServer,
                       [out] HPROCESS *pProcessHandle);

    //
    // For machines on networks with port restrictions due to firewalls
    // we need to centrally (for a system) manage port allocation.
    //
    // Regardless of the general policy for the network, applications
    // either want a "standard" port which is not available from an
    // external network (system services usually) or want a "restricted"
    // port because their service needs to be avaiable to both internal
    // and external users.
    // The endpoint mapper manages ranges of both kinds of ports and
    // will return "restricted" (if fRestricted) or "standard" ports
    // as required by applications.
    // If *pPort is zero then any port maybe used.
    //

    typedef [v1_enum] enum {
        PORT_INTERNET = 1,
        PORT_INTRANET,
        PORT_DEFAULT
        } PORT_TYPE;

    error_status_t
    AllocateReservedIPPort(
        [in] HPROCESS hProcess,
        [in] PORT_TYPE DesiredPort,
        [out] long *pAllocationStatus,
        [out] unsigned short *pPort);


    void
    ept_insert_ex(
        [in] handle_t hEpMapper,
        [in, out] ept_cleanup_handle_t *hEpCleanup,
        [in] unsigned32 num_ents,
        [in, size_is(num_ents)] ept_entry_t entries[],
        [in] unsigned long replace,
        [out] error_status *status
        );

    void
    ept_delete_ex (
        [in] handle_t hEpMapper,
        [in, out] ept_cleanup_handle_t *hEpCleanup,
        [in] unsigned32 num_ents,
        [in, size_is(num_ents)] ept_entry_t entries[],
        [out] error_status *status
        );

#if 0
    //
    // We only allocate local processes to register and delete
    // bindings from the endpoint mapper.  The remote version
    // always fails with access denided.
    //
    // The context handle parameter is used to allow the endpoint
    // mapper to cleanup entries in the endpoint mapper database
    // when a process dies.
    //

    void
    ept_insert(
        [in] handle_t hServer,
        [in] HPROCESS hProcess,
        [in] unsigned32 num_ents,
        [in, size_is(num_ents)] ept_entry_t entries[],
        [in] unsigned long replace,
        [out] error_status *status
        );

    void
    ept_delete (
        [in] handle_t hServer,
        [in] HPROCESS hProcess,
        [in] unsigned32 num_ents,
        [in, size_is(num_ents)] ept_entry_t entries[],
        [out] error_status *status
        );
#endif

} // interface localepmp

#endif // !MAC && !MPPC