/*
 * Copyright (c) 2010 Apple Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1.  Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 * 2.  Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 * 3.  Neither the name of Apple Inc. ("Apple") nor the names of its
 *     contributors may be used to endorse or promote products derived from
 *     this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * Portions of this software have been released under the following terms:
 *
 * (c) Copyright 1989-1993 OPEN SOFTWARE FOUNDATION, INC.
 * (c) Copyright 1989-1993 HEWLETT-PACKARD COMPANY
 * (c) Copyright 1989-1993 DIGITAL EQUIPMENT CORPORATION
 *
 * To anyone who acknowledges that this file is provided "AS IS"
 * without any express or implied warranty:
 * permission to use, copy, modify, and distribute this file for any
 * purpose is hereby granted without fee, provided that the above
 * copyright notices and this notice appears in all source code copies,
 * and that none of the names of Open Software Foundation, Inc., Hewlett-
 * Packard Company or Digital Equipment Corporation be used
 * in advertising or publicity pertaining to distribution of the software
 * without specific, written prior permission.  Neither Open Software
 * Foundation, Inc., Hewlett-Packard Company nor Digital
 * Equipment Corporation makes any representations about the suitability
 * of this software for any purpose.
 *
 * Copyright (c) 2007, Novell, Inc. All rights reserved.
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1.  Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 * 2.  Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 * 3.  Neither the name of Novell Inc. nor the names of its contributors
 *     may be used to endorse or promote products derived from this
 *     this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * @APPLE_LICENSE_HEADER_END@
 */

/*
**
**  NAME:
**
**      rpcpvt.idl
**
**  FACILITY:
**
**      Remote Procedure Call
**
**  ABSTRACT:
**
**  This file contains the PRIVATE interface to the Common Communications
**  Service of the RPC facility.
**
**  NOTE WELL: The existence, signature, and semantics of anything in
**  this file is subject to change without notice and should thus not
**  be depended on by application writers.
**
**
*/

[local] interface rpcpvt
{

import "dce/lbase.idl";
import "dce/rpcbase.idl";
import "dce/iovector.idl";
import "dce/rpcsts.idl";

/*************************************************************************/
/************************  Deprecated names  *****************************/
/*************************************************************************/

/*
 * These are names that we used for a while, changed, but don't feel
 * like fixing all the uses of right now.
 */
const long rpc_c_authn_dce_private          = rpc_c_authn_dce_secret;
const long rpc_c_protseq_max_calls_default  = rpc_c_protseq_max_reqs_default;

const long rpc_s_unknown_auth_protocol      = rpc_s_unknown_authn_service;
const long rpc_s_cant_create_sock           = rpc_s_cant_create_socket;
const long rpc_s_cant_bind_sock             = rpc_s_cant_bind_socket;
const long rpc_s_cant_listen_sock           = rpc_s_cant_listen_socket;
const long rpc_s_no_ns_privilege            = rpc_s_no_ns_permission;
const long rpc_s_unsupported_authn_level    = rpc_s_unsupported_protect_level;
const long rpc_s_authn_level_mismatch       = rpc_s_protect_level_mismatch;

const long rpc_c_authn_level_default        = rpc_c_protect_level_default;
const long rpc_c_authn_level_none           = rpc_c_protect_level_none;
const long rpc_c_authn_level_connect        = rpc_c_protect_level_connect;
const long rpc_c_authn_level_call           = rpc_c_protect_level_call;
const long rpc_c_authn_level_pkt            = rpc_c_protect_level_pkt;
const long rpc_c_authn_level_pkt_integrity  = rpc_c_protect_level_pkt_integ;
const long rpc_c_authn_level_pkt_privacy    = rpc_c_protect_level_pkt_privacy;

/***********************************************************************
 *
 *  NSI typedefs for compatibility with existing (pre-DCE V1.0) code.
 *
 ***********************************************************************/
/*
 * Inquiry handle.
 */
typedef rpc_ns_handle_t     rpc_ns_inq_handle_t, *rpc_ns_inq_handle_p_t;

/*
 * Lookup handle.
 */
typedef rpc_ns_handle_t     rpc_ns_lookup_handle_t, *rpc_ns_lookup_handle_p_t;

/*
 * Import handle.
 */
typedef rpc_ns_handle_t     rpc_ns_import_handle_t, *rpc_ns_import_handle_p_t;

/*************************************************************************/
/*******************  Comm Services Binding object  **********************/
/*************************************************************************/

/*
 * R P C _ B I N D I N G _ H A N D L E _ C O P Y
 *
 * Duplicate a binding handle. Create a duplicate handle to an existing
 * (now shared) binding object.  This is the ONLY legal way to create
 * a duplicate handle to a shared binding object.  I.E. the following
 * C code is ILLEGAL:
 *      new_handle = existing_handle;
 * A duplicate handle is freed by rpc_binding_free().  Duplicate handles
 * are useful for properly managing a binding object that is concurrently
 * shared among a number of threads.
 */
void rpc_binding_handle_copy
(
    [in]        rpc_binding_handle_t    source_binding,
    [out]       rpc_binding_handle_t    *destination_binding,
    [out]       unsigned32              *status
);

/*
 * R P C _ B I N D I N G _ H A N D L E _ E Q U A L
 *
 * Compare two binding handles for equality. Returns true iff the two
 * handles reference the same binding object.  (see
 * rpc_binding_handle_copy(); rpc_binding_copy() do not reference the
 * same binding object).
 */
boolean32 rpc_binding_handle_equal
(
    [in]        rpc_binding_handle_t    binding1,
    [in]        rpc_binding_handle_t    binding2,
    [out]       unsigned32              *status
);

/*
 * R P C _ B I N D I N G _ S E R V E R _ T O _ C L I E N T
 *
 * NOTE: This description uses old terminology.
 *
 * Convert a server binding handle to a client handle.  The new handle's
 * endpoint is reset and it has no associated authentication information.
 *
 * Server binding handles are those created by the runtime and provided
 * to the server manager as a result of a [handle_t] RPC parameter.
 */
void rpc_binding_server_to_client
(
    [in]        rpc_binding_handle_t    sbinding_handle,
    [out]       rpc_binding_handle_t    *cbinding_handle,
    [out]       unsigned32              *status
);

/*
 * R P C _ B I N D I N G _ T O _ E P M A P
 *
 * Given a binding handle to a server, return a binding handle to the
 * EP map on that host.  If input_binding is NULL, return a binding to
 * the EP map on the local host.
 */
void rpc_binding_to_epmap
(
    [in]        rpc_binding_handle_t    input_binding,
    [out]       rpc_binding_handle_t    *output_binding,
    [out]       unsigned32              *status
);

/*************************************************************************/
/********************  Comm Services Server object  **********************/
/*************************************************************************/

/*
 * An opaque handle representing a server thread pool.
 */
typedef rpc_opaque_ptr_t    rpc_thread_pool_handle_t, *rpc_thread_pool_handle_p_t;

/*
 * R P C _ S E R V E R _ C R E A T E _ T H R E A D _ P O O L
 *
 * Create a pool of "num_threads" threads to execute incoming RPC
 * requests.  Return a handle onto that pool.
 * The pool exists until the pool is freed; the pool's threads are created
 * when rpc_server_listen() is called and destroyed when
 * rpc_server_listen() returns.
 */
void rpc_server_create_thread_pool
(
    [in]        unsigned32              num_threads,
    [out]       rpc_thread_pool_handle_t *phandle,
    [out]       unsigned32              *status
);

/*
 * R P C _ S E R V E R _ F R E E _ T H R E A D _ P O O L
 *
 * Destroy a thread pool once all RPCs executing using that pool
 * complete.  If wait_flag == true, block until the pool is destroyed.
 */
void rpc_server_free_thread_pool
(
    [in, out]   rpc_thread_pool_handle_t *phandle,
    [in]        boolean32               wait_flag,
    [out]       unsigned32              *status
);

/*
 * Signature of an application-supplied function used to determine which
 * thread pool to use for an incoming RPC request on object "obj_uuid",
 * using the "opnum"th operation in interface "if_id".
 *
 * status (and phandle) return values:
 *      0 - OK; phandle != NULL: execute the call with a phandle thread.
 *                               If all phandle threads are busy, execute
 *                               the call with the first available phandle
 *                               thread or default pool thread (subject
 *                               to runtime call rejection due to phandle
 *                               max queue length limits).
 *              phandle == NULL: execute the call with a default pool
 *                               thread.  If all default pool threads
 *                               are busy, execute the call with the
 *                               first available default default pool
 *                               thread (subject to runtime call rejection
 *                               due to default pool max queue length
 *                               limits).
 *      non-0 - failure:    do not execute the call
 */
typedef void (*rpc_thread_pool_fn_t)
(
    [in]        uuid_p_t                obj_uuid,
    [in]        rpc_if_id_p_t           if_id,
    [in]        unsigned32              opnum,
    [out]       rpc_thread_pool_handle_t *phandle,
    [out]       unsigned32              *status
);

/*
 * R P C _ S E R V E R _ S E T _ T H R E A D _ P O O L _ F N
 *
 * Supply the runtime with a function to be called to determine
 * which pool an incoming RPC request should be run in.
 *
 * !!! NOTE: Your application assumes certain responsibilities if it
 * uses thread pools. The applications's pool_fn operation is called
 * back to from the runtime internal listener thread hence it should
 * operate as efficiently as possible and not block for an extended period.
 * The pool_fn MUST NOT call back into the runtime in performing its
 * processing (e.g. it can't call rpc_object_inq_type(), ...).
 */
void rpc_server_set_thread_pool_fn
(
    [in]        rpc_thread_pool_fn_t    pool_fn,
    [out]       unsigned32              *status
);

/*
 * R P C _ S E R V E R _ S E T _ T H R E A D _ P O O L _ Q L E N
 *
 * Allow the application to adjust the size of a thread pool's call
 * queue.  That is, this routine allows the application to specify
 * the maximum number of calls that will be queued for execution by
 * a particular thread pool, if all of the pool's call threads are
 * already in use.  (Note that this function will only allow the
 * queue size to be increased.  Attempts to decrease the queue size
 * are ignored.)
 */
void rpc_server_set_thread_pool_qlen
(
    [in]        rpc_thread_pool_handle_t  phandle,
    [in]        unsigned32                queue_size,
    [out]       unsigned32                *status
);

/*************************************************************************/
/*******************  Comm Services Tower object  ************************/
/*************************************************************************/

/*
 * R P C _ T O W E R _ T O _ B I N D I N G
 *
 * Creates a binding handle from the canonical representation
 * of a protocol tower.
 */
void rpc_tower_to_binding
(
    [in]        byte_p_t                prot_tower,
    [out]       rpc_binding_handle_t    *binding,
    [out]       unsigned32              *status
);

/*
 * R P C _ T O W E R _ V E C T O R _ F R O M _ B I N D I N G
 *
 * Creates a tower vector (of twr_t's) from a binding handle.
 */
void rpc_tower_vector_from_binding
(
    [in]        rpc_if_handle_t         if_spec,
    [in]        rpc_binding_handle_t    binding,
    [out]       rpc_tower_vector_p_t    *twr_vector,
    [out]       unsigned32              *status
);

/*
 * R P C _ T O W E R _ V E C T O R _ F R E E
 *
 * Free the memory allocated by the RPC runtime for the protocol towers
 * contained in the vector and the vector itself. A NULL pointer will be
 * returned.
 */
void rpc_tower_vector_free
(
    [in, out]   rpc_tower_vector_p_t    *twr_vector,
    [out]       unsigned32              *status
);

/*************************************************************************/
/**********************  Name Services Entry object  *********************/
/*************************************************************************/

/*
 * R P C _ N S _ E N T R Y _ I N Q _ R E S O L U T I O N
 *
 * Inquire on the resolution of a name service entry
 */
void rpc_ns_entry_inq_resolution
(
    [in]        unsigned32              entry_name_syntax,
    [in]        unsigned_char_p_t       entry_name,
    [out]       unsigned_char_p_t       *resolved_name,
    [out]       unsigned_char_p_t       *unresolved_name,
    [out]       unsigned32              *status
);

/*************************************************************************/
/*********************  Name Services Authentication  ********************/
/*************************************************************************/
/*
 * R P C _ N S _ S E T _ A U T H N
 *
 * Set the Name Services Authentication
 */
void rpc_ns_set_authn
(
    [in]        boolean32               authn,
    [out]       boolean32               *previous_authn,
    [out]       unsigned32              *status
);

/*************************************************************************/
/**************************  Management Services  ************************/
/*************************************************************************/

/*
 * R P C _ M G M T _ I N Q _ D F L T _ A U T H N _ L E V E L
 *
 * Returns the default protection level for an authentication service.
 */
void rpc_mgmt_inq_dflt_authn_level
(
    [in]        unsigned32              authn_svc,
    [out]       unsigned32              *authn_level,
    [out]       unsigned32              *st
);

/*
 * R P C _ M G M T _ S E T _ M A X _ C O N C U R R E N C Y
 *
 * Notify RPC runtime of how many concurrent RPC threads are required
 * by the application.
 */
void rpc_mgmt_set_max_concurrency
(
    [in]        unsigned32              max_client_calls,
    [in]        unsigned32              max_server_calls,
    [out]       unsigned32              *status
);

/*
 * R P C _ M G M T _ G E T _ M A X _ C O N C U R R E N C Y
 *
 * Allows an application to determine how many concurrent RPC calls can
 * be supported by the runtime.
 */
unsigned32 rpc_mgmt_get_max_concurrency
(
);

/*
 * R P C _ M G M T _ S E T _ S E R V E R _ C O M _ T I M E O U T
 *
 * Set the default comm timeout setting for all server calls.
 */
void rpc_mgmt_set_server_com_timeout
(
    [in]        unsigned32              timeout,
    [out]       unsigned32              *status
);

/*
 * R P C _ M G M T _ I N Q _ S E R V E R _ C O M _ T I M E O U T
 *
 * Returns the default comm timeout setting in use for all server calls.
 */
unsigned32 rpc_mgmt_inq_server_com_timeout
(
);

/*************************************************************************/
/*******************  Stub Services Binding object  **********************/
/*************************************************************************/

/*
 * R P C _ B I N D I N G _ I N Q _ C L I E N T
 *
 * Inquire what client address space a binding handle refers to.
 */
void rpc_binding_inq_client
(
    [in]        rpc_binding_handle_t    binding_handle,
    [out]       rpc_client_handle_t     *client_handle,
    [out]       unsigned32              *status
);

/*************************************************************************/
/*******************  Stub Services Call object  *************************/
/*************************************************************************/

/*
 * R P C _ C A L L _ B L O C K _ U N T I L _ F R E E
 *
 * This routine will block until all marshaled RPC output arguments have
 * been transmitted and acknowledged. It is provided for use by the server
 * stub when the marshaled arguments are contained in buffers which are on
 * stack. The danger is that the server stub would return to the RPC
 * runtime thereby invalidating its stack and the buffer contents.
 */
void rpc_call_block_until_free
(
    [in]        rpc_call_handle_t       call_handle,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ C A N C E L
 *
 * Forward a local cancel to the remote RPC thread identified by the call
 * handle provided.
 */
void rpc_call_cancel
(
    [in]        rpc_call_handle_t       call_handle,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ D I D _ M G R _ E X E C U T E
 *
 * Return whether or not the manager routine for the call identified
 * by the call handle has executed.
 */
boolean32 rpc_call_did_mgr_execute
(
    [in]        rpc_call_handle_t       call_handle,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ E N D
 *
 * End a Remote Procedure Call. This is the last in the sequence of
 * calls by the client stub.
 */
void rpc_call_end
(
    [in, out]   rpc_call_handle_t       *call_handle,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ T R A N S M I T _ F A U L T
 *
 * Forward an exception to the remote RPC thread identified by the call
 * handle.
 */
void rpc_call_transmit_fault
(
    [in]        rpc_call_handle_t       call_handle,
    [in]        rpc_iovector_p_t        fault_info,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ R E C E I V E
 *
 * Return a buffer of marshaled arguments from the remote thread.
 */
void rpc_call_receive
(
    [in]        rpc_call_handle_t       call_handle,
    [out]       rpc_iovector_elt_t      *call_args,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ R E C E I V E _ F A U L T
 *
 * Return a buffer of marshaled fault information from the remote thread.
 */
void rpc_call_receive_fault
(
    [in]        rpc_call_handle_t       call_handle,
    [out]       rpc_iovector_elt_t      *fault_info,
    [out]       ndr_format_t            *remote_ndr_fmt,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ S T A R T
 *
 * Begin a Remote Procedure Call. This is the first in a sequence of
 * calls by the client stub. Return the information needed to marshal input
 * arguments.
 */
void rpc_call_start
(
    [in]        rpc_binding_handle_t    binding_handle,
    [in]        unsigned32              call_options,
    [in]        rpc_if_handle_t         if_spec,
    [in]        unsigned32              operation_number,
    [out]       rpc_call_handle_t       *call_handle,
    [out]       rpc_transfer_syntax_t   *xfer_syntax,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ T R A N S C E I V E
 *
 *
 * Transmit a vector of marshaled arguments to the remote thread. Use the
 * call handle as the identifier of the RPC being performed. Block until
 * the first buffer of marshaled output arguments has been received.
 */
void rpc_call_transceive
(
    [in]        rpc_call_handle_t       call_handle,
    [in]        rpc_iovector_p_t        in_call_args,
    [out]       rpc_iovector_elt_t      *out_call_args,
    [out]       ndr_format_t            *remote_ndr_fmt,
    [out]       unsigned32              *status
);

/*
 * R P C _ C A L L _ T R A N S M I T
 *
 * Transmit a vector of marshaled arguments to the remote thread. Use the
 * call handle as the identifier of the RPC being performed.
 */
void rpc_call_transmit
(
    [in]        rpc_call_handle_t       call_handle,
    [in]        rpc_iovector_p_t        call_args,
    [out]       unsigned32              *status
);

/*************************************************************************/
/******************  Stub Services Network object  ***********************/
/*************************************************************************/

/*
 * R P C _ N E T W O R K _ M A I N T A I N _ L I V E N E S S
 *
 * This routine tells the RPC runtime to actively keep communications alive
 * with the process identified in the binding.
 */
void rpc_network_maintain_liveness
(
    [in]        rpc_binding_handle_t    binding_handle,
    [out]       unsigned32              *status
);

/*
 * R P C _ N E T W O R K _ M O N I T O R _ L I V E N E S S
 *
 * This routine tells the RPC runtime to call the routine provided if
 * communications are lost to the process represented by the client
 * handle provided.
 */
void rpc_network_monitor_liveness
(
    [in]        rpc_binding_handle_t    binding_handle,
    [in]        rpc_client_handle_t     client_handle,
    [in]        rpc_network_rundown_fn_t rundown_fn,
    [out]       unsigned32              *status
);

/*
 * R P C _ N E T W O R K _ S T O P _ M A I N T A I N I N G
 *
 * This routine tells the RPC runtime to cancel rpc_network_maintain_liveness.
 */
void rpc_network_stop_maintaining
(
    [in]        rpc_binding_handle_t    binding_handle,
    [out]       unsigned32              *status
);

/*
 * R P C _ N E T W O R K _ S T O P _ M O N I T O R I N G
 *
 * This routine tells the RPC runtime to cancel rpc_network_monitor_liveness.
 */
void rpc_network_stop_monitoring
(
    [in]        rpc_binding_handle_t    binding_handle,
    [in]        rpc_client_handle_t     client_handle,
    [out]       unsigned32              *status
);

/*
 * R P C _ N E T W O R K _ C L O S E
 *
 * This routine tells the RPC runtime to close the underlying
 * association with a binding handle.
 */
void rpc_network_close
(
    [in]        rpc_binding_handle_t    binding_handle,
    [out]       unsigned32              *status
);

/*************************************************************************/
/******************  Stub Services Utility object  ***********************/
/*************************************************************************/

/*
 * R P C _ U T I L _ S T R C V T
 *
 * Perform ASCII <-> EBCDIC conversion.
 */
void rpc_util_strcvt
(
    [in]        boolean32               to_ascii,
    [in]        unsigned32              len,
    [in]        byte_p_t                src,
    [in]        byte_p_t                dst
);

/*************************************************************************/
/*******************  Comm Services Utilities **********************/
/*************************************************************************/

/*
 * R P C _ S T R A L L O C
 *
 * Make a copy of the input string into allocated storage.
 */
unsigned_char_p_t rpc_stralloc
(
    [in]        unsigned_char_p_t       string
);

}