/*++

Copyright (c) 1991 Microsoft Corporation

Module Name:

    epmp.idl

Abstract:

    This file specifies the interface to the endpoint mapper

Author:

    Bharat Shah  (barats) 2-11-92

Revision History:
    barats  3-13-92 Changed to new spec.
    barats  5-10-92 Midl related bugbug removerd
    mariogo 6-08-94 Changed to full pointers.
    mariogo 4-24-96 Added local interface for local runtime <-> rpcss calls.

--*/

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

#if 0

//Part of the standard interface attributes, but we use our own table of
//protseqs and endpoints.  Avoid duplication.

  endpoint("ncadg_ip_udp:[135]", "ncadg_dds:[12]", "ncacn_ip_tcp:[135]",
           "ncacn_dnet_nsp:[#69]"),

#endif

[
  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;

#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;


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
    );

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
    );

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
    );


}

#if NTENV

[
uuid(0b0a6584-9e0f-11cf-a3cf-00805f68cb1b),
version(1.0)
]
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);

#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

}

#endif