/* @(#)66	1.6  src/rpc/sys_idl/ep.idl, rpc.idl.src, aixdce13, 940405a  2/24/94  12:19:06 */
/*
 * COMPONENT_NAME:  rpc.idl.src
 *
 * FUNCTIONS:
 *
 * ORIGINS: 72
 *
 */
/*
 * (c) Copyright 1990, 1991 OPEN SOFTWARE FOUNDATION, INC.
 * ALL RIGHTS RESERVED
 * COPYRIGHT NOTICE
 * Copyright (c) 1990, 1991, 1992, 1993 Open Software Foundation, Inc.
 * ALL RIGHTS RESERVED (DCE).  See the file named COPYRIGHT.DCE in the
 * src directory for the full copyright text.
 */
/*
 * HISTORY
 * $Log: ep.idl,v $
 * Revision 1.1.2.3  1993/01/03  23:56:19  bbelch
 *	Embedding copyright notice
 *	[1993/01/03  20:14:49  bbelch]
 *
 * Revision 1.1.2.2  1992/12/23  21:19:41  zeliff
 *	Embedding copyright notice
 *	[1992/12/23  15:46:30  zeliff]
 *
 * Revision 1.1  1992/01/19  03:13:32  devrcs
 *	Initial revision
 *
 * $EndLog$
 */
/*
**  Copyright (c) 1989 by
**	Hewlett-Packard Company, Palo Alto, Ca. &
**	Digital Equipment Corporation, Maynard, Mass.
**
**
**  NAME:
**
**	ep.idl
**
**  FACILITY:
**
**	RPC Daemon
**
**  ABSTRACT:
**
**  The Endpoint Map object exists to support the specific problem of
**  network transports having a small endpoint namespace (e.g. UDP/IP).
**  Such transports require that objects (servers) use dynamically
**  generated endpoints, registering this endpoint with an endpoint map
**  object and actually exporting an endpoint to the endpoint map object.
**  Clients use an endpoint map either directly or indirectly (in the
**  case of connection oriented or connectionless transports respectively)
**  to determine the real endpoint of the object (server).
**
**  Note that the "ip" and "dds" well known endpoints are those
**  assigned to the NCS 1.5.1 Local Location Broker.
**
**
*/

/*
 *  CMVC Feature 9606
 *  Add NETBIOS endpoints and #ifdef IBMOS2.
 */
#ifdef IBMOS2
[
 uuid(e1af8308-5d1f-11c9-91a4-08002b14a0fa), version(3.0),
 endpoint("ncadg_ip_udp:[135]", "ncadg_dds:[12]", "ncacn_ip_tcp:[135]",
	  "ncacn_dnet_nsp:[#69]", "ncacn_nb_stream:[135S]",
          "ncadg_nb_dgram:[135D]"),
 pointer_default(ptr)
]
#else
[
 uuid(e1af8308-5d1f-11c9-91a4-08002b14a0fa), version(3.0),
 endpoint("ncadg_ip_udp:[135]", "ncadg_dds:[12]", "ncacn_ip_tcp:[135]",
	  "ncacn_dnet_nsp:[#69]"),
 pointer_default(ptr)
]
#endif

interface ept
{

import "dce/nbase.idl";
import "dce/rpctypes.idl";

const long ept_max_annotation_size  = 64;


typedef struct ept_entry_t     /* OT7619, CMVC5209, ept_entry_t added */
{
		uuid_t	    object;
		twr_p_t     tower;
    [string]	char	    annotation[ept_max_annotation_size];
} ept_entry_t, *ept_entry_p_t;


typedef [context_handle] void *ept_lookup_handle_t;


/*
 * E P T _ I N S E R T
 *
 * Add the specified entries to an endpoint map.
 */

void ept_insert(
    [in]	    handle_t		h,
    [in]	    unsigned32		num_ents,
    [in, size_is(num_ents)]
		    ept_entry_t 	entries[],
    [in]	    boolean32		replace,
    [out]	    error_status_t	*status
);


/*
 * E P T _ D E L E T E
 *
 * Delete the specified entries from an endpoint map.
 */

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


/*
 * E P T _ L O O K U P
 *
 * Lookup entries in an endpoint map.
 *
 */

[idempotent]
void ept_lookup(
    [in]	    handle_t		h,
    [in]	    unsigned32		inquiry_type,
    [in]	    uuid_p_t		object,
    [in]	    rpc_if_id_p_t	interface_id,
    [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_t	*status
);


/*
 * E P T _ M A P
 *
 * Apply some algorithm (using the fields in the map_tower)
 * to an endpoint map to produce a list of protocol towers.
 */

[idempotent]
void ept_map(
    [in]	    handle_t		h,
    [in]	    uuid_p_t		object,
    [in]	    twr_p_t		map_tower,
    [in, out]	    ept_lookup_handle_t *entry_handle,
    [in]	    unsigned32		max_towers,
    [out]	    unsigned32		*num_towers,
    [out, length_is(*num_towers), size_is(max_towers)]
		    twr_p_t		towers[],
    [out]	    error_status_t	*status
);


/*
 * E P T _ L O O K U P _ H A N D L E _ F R E E
 *
 * Free an ept_lookup or ept_map context_handle
 */

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


/*
 * E P T _ I N Q _ O B J E C T
 *
 * Inquire Endpoint Map's object id.
 */

[idempotent]
void ept_inq_object(
    [in]	    handle_t		h,
    [out]	    uuid_t		*ept_object,
    [out]	    error_status_t	*status
);

/*
 * E P T _ M G M T _ D E L E T E
 *
 * Delete matching entries from an endpoint map.
 *
 * All entries that match the tower's interface uuid,
 * version, and network address are deleted.  If an
 * object uuid is specified, the entries which are
 * deleted must also match the object uuid.
 */

void ept_mgmt_delete(
    [in]	    handle_t		h,
    [in]	    boolean32		object_speced,
    [in]	    uuid_p_t		object,
    [in]	    twr_p_t		tower,
    [out]	    error_status_t	*status
);

}
