NAME

rpc_intro - Introduction to the NCS 2.0 RPC API runtime

DESCRIPTION

This introduction gives general information about the NCS 2.0 RPC Application Programming Interface (API) and an overview of the following parts of the RPC API runtime:

       •Runtime services

       •Environment variables

       •Data types and structures

       •Permissions required

       •Frequently used routine arguments

GENERAL INFORMATION

This section contains topics, beyond those directly related to the RPC API, that application programmers need to know. 

IDL-to-C Mappings

The Interface Definition Language (IDL) compiler converts an interface definition into output files.  The intro(1rpc) reference page contains a summary of the idl command which invokes the IDL compiler. 

Additional information about the IDL compiler appears in the following table that shows the IDL base types and the IDL-to-C mappings. 

The table lists the IDL base data type specifiers.  Where applicable, the table shows the size of the corresponding transmittable type and the type macro emitted by the IDL compiler for resulting declarations. 

Table 0-0.  Base Data Type Specifiers

	Specifier			Type Macro
(sign)	(size)	(type)	Size	Emitted by idl
	small	int	8 bits	idl_small_int
	short	int	16 bits	idl_short_int
	long	int	32 bits	idl_long_int
	hyper	int	64 bits	idl_hyper_int
unsigned	small	int	8 bits	idl_usmall_int
unsigned	short	int	16 bits	idl_ushort_int
unsigned	long	int	32 bits	idl_ulong_int
unsigned	hyper	int	64 bits	idl_uhyper_int
		float	32 bits	idl_short_float
		double	64 bits	idl_long_float
		char	8 bits	idl_char
		boolean	8 bits	idl_boolean
		byte	8 bits	idl_byte
		void	--	idl_void_p_t
		handle_t	--	--

Note that you can use the idl_ macros in the code you write for an application to ensure that your type declarations are consistent with those in the stubs, even when the application is ported to another platform.  The idl_ macros are especially useful when passing constant values to RPC calls.  For maximum portability, all constants passed to RPC calls declared in your network interfaces should be cast to the appropriate type, because the size of integer constants (like the size of the int data type) is unspecified in the C language. 

The idl_ macros are defined in <dce/idlbase.h>, which is included by header files that the IDL compiler generates. 

Management Commands for Programmers

In addition to the idl command for programmers, RPC provides two management commands for the RPC control program and the RPC daemon as follows:

       •rpccp — Accesses RPCCP, the RPC control program.  This program provides a set of commands for accessing the operations of the RPC name service interface (NSI operations).  RPCCP also supports showing the elements of the local endpoint map and removing elements from it. 

NOTE: For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

You can manage the name service with RPCCP commands or with RPC runtime routines.  For example, suppose you want to obtain the members of a group.  You can give the show group command to RPCCP or you can write an application program that calls the RPC runtime routines rpc_ns_group_mbr_inq_begin, rpc_ns_group_mbr_inq_next, and rpc_ns_group_mbr_inq_done. 

       •rpcd — Starts RPCD, the RPC daemon.  The daemon maintains the local endpoint map for RPC servers and looks up endpoints for RPC clients. 

See the Managing NCS Software for more information about these two management commands. 

OVERVIEW OF RPC RUNTIME SERVICES

The RPC runtime services consist of RPC routines that perform a variety of operations. 

Note: The RPC API is thread safe and synchronous cancel safe (in the context of POSIX threads).  However, the RPC API is not asynchronous cancel safe. 

The rest of this overview consists of the following:

       •A list of stub support routines

       •An explanation of abbreviations in the names of the non-stub support routines

       •A list of non-stub support routines

An alphabetical list of the RPC stub support routines follows.  With each routine name is its description and the type of application program that most likely calls the routine. 

rpc_ss_allocateAllocates memory within the RPC stub memory management scheme.  (Usually server, possibly client)

rpc_ss_destroy_client_context
Reclaims the client memory resources for the context handle, and sets the context handle to null.  (Client)

rpc_ss_disable_allocateReleases resources and allocated memory.  (Client)

rpc_ss_enable_allocateEnables the allocation of memory by the rpc_ss_allocate routine when not in manager code.  (Client)

rpc_ss_freeFrees memory allocated by the rpc_ss_allocate routine.  (Usually server, possibly client)

rpc_ss_get_thread_handleGets a thread handle for the manager code before it spawns additional threads, or for the client code when it becomes a server.  (Usually server, possibly client)

rpc_ss_register_auth_infoRegisters authentication and authorization information for an interface.  (Client)

rpc_ss_set_client_alloc_freeSets the memory allocation and freeing mechanism used by the client stubs, thereby overriding the default routines the client stub uses to manage memory for pointed-to nodes.  (Client)

rpc_ss_set_thread_handleSets the thread handle for either a newly created spawned thread or for a server that was formerly a client and is ready to be a client again.  (Usually server, possibly client)

rpc_ss_swap_client_alloc_free
Exchanges the current memory allocation and freeing mechanism used by the client stubs with one supplied by the client. (Client)

An alphabetical list of abbreviations in the names of the non-stub support routines follows.  The list can help you remember the names more easily.  For example, consider the routine name rpc_mgmt_ep_elt_inq_begin.  Use the next list to expand the name to "RPC management endpoint element inquiry begin", which summarizes the description "Creates an inquiry context for viewing the elements in a local or remote endpoint map.  (Management)."

authauthentication, authorization

comcommunication

dcedistributed computing environment

dfltdefault

eltelement

ependpoint

expexpiration

fnfunction

ididentifier

ifinterface

inqinquiry

mbrmember

mgmtmanagement

nsname service

protseqprotocol sequence

rpcremote procedure call

statsstatistics

An alphabetical list of the RPC non-stub support routines follows.  With each routine name is its description and the type of application program that most likely calls the routine. 

dce_error_inq_textReturns the message text for a status code.  (Client, server, or management)

rpc_binding_copyReturns a copy of a binding handle.  (Client or server)

rpc_binding_freeReleases binding handle resources.  (Client or server)

rpc_binding_from_string_binding
Returns a binding handle from a string representation of a binding handle.  (Client or management)

rpc_binding_inq_auth_clientReturns authentication and authorization information from the binding handle for an authenticated client.  (Server)

rpc_binding_inq_auth_infoReturns authentication and authorization information from a server binding handle.  (Client)

rpc_binding_inq_objectReturns the object UUID from a binding handle.  (Client or server)

rpc_binding_resetResets a server binding handle so the host remains specified, but the server instance on that host is unspecified.  (Client or management)

rpc_binding_server_from_client
Converts a client binding handle to a server binding handle.  (Server)

rpc_binding_set_auth_infoSets authentication and authorization information into a server binding handle.  (Client)

rpc_binding_set_objectSets the object UUID value into a server binding handle.  (Client)

rpc_binding_to_string_binding
Returns a string representation of a binding handle.  (Client, server, or management)

rpc_binding_vector_freeFrees the memory used to store a vector and binding handles.  (Client or server)

rpc_ep_registerAdds to, or replaces, server address information in the local endpoint map.  (Server)

rpc_ep_register_no_replaceAdds to server address information in the local endpoint map.  (Server)

rpc_ep_resolve_bindingResolves a partially bound server binding handle into a fully bound server binding handle.  (Client or management)

rpc_ep_unregisterRemoves server address information from the local endpoint map.  (Server)

rpc_if_id_vector_freeFrees a vector and the interface identifier structures it contains.  (Client, server, or management)

rpc_if_inq_idReturns the interface identifier for an interface specification.  (Client or server)

rpc_mgmt_ep_elt_inq_beginCreates an inquiry context for viewing the elements in a local or remote endpoint map.  (Management)

rpc_mgmt_ep_elt_inq_doneDeletes the inquiry context for viewing the elements in a local or remote endpoint map.  (Management)

rpc_mgmt_ep_elt_inq_nextReturns one element at a time from a local or remote endpoint map.  (Management)

rpc_mgmt_ep_unregisterRemoves server address information from a local or remote endpoint map.  (Management)

rpc_mgmt_inq_com_timeoutReturns the communication timeout value in a binding handle.  (Client)

rpc_mgmt_inq_dflt_protect_level
Returns the default protection level for an authentication service.  (Client or server)

rpc_mgmt_inq_if_idsReturns a vector of interface identifiers of interfaces a server offers.  (Client, server, or management)

rpc_mgmt_inq_server_princ_name
Returns a server’s principal name.  (Client, server, or management)

rpc_mgmt_inq_statsReturns RPC runtime statistics.  (Client, server, or management)

rpc_mgmt_is_server_listening
Tells whether a server is listening for remote procedure calls.  (Client, server, or management)

rpc_mgmt_set_authorization_fn
Establishes an authorization function for processing remote calls to a server’s management routines.  (Server)

rpc_mgmt_set_cancel_timeout
Sets the lower bound on the time to wait before timing out after forwarding a cancel.  (Client)

rpc_mgmt_set_com_timeoutSets the communication timeout value in a binding handle.  (Client)

rpc_mgmt_set_server_stack_size
Specifies the stack size for each server thread.  (Server)

rpc_mgmt_stats_vector_freeFrees a statistics vector.  (Client, server, or management)

rpc_mgmt_stop_server_listening
Tells a server to stop listening for remote procedure calls.  (Client, server, or management)

rpc_network_inq_protseqsReturns all protocol sequences supported by both the RPC runtime and the operating system.  (Client or server)

rpc_network_is_protseq_valid
Tells whether the specified protocol sequence is supported by both the RPC runtime and the operating system.  (Client or server)

rpc_ns_binding_exportEstablishes a name service database entry with binding handles or object UUIDs for a server.  (Server)

rpc_ns_binding_import_begin
Creates an import context for an interface and an object in the name service database.  (Client)

rpc_ns_binding_import_doneDeletes the import context for searching the name service database.  (Client)

rpc_ns_binding_import_nextReturns a binding handle of a compatible server (if found) from the name service database.  (Client)

rpc_ns_binding_inq_entry_name
Returns the name of an entry in the name service database from which the server binding handle came.  (Client)

rpc_ns_binding_lookup_begin
Creates a lookup context for an interface and an object in the name service database.  (Client)

rpc_ns_binding_lookup_doneDeletes the lookup context for searching the name service database.  (Client)

rpc_ns_binding_lookup_nextReturns a list of binding handles of one or more compatible servers (if found) from the name service database.  (Client)

rpc_ns_binding_selectReturns a binding handle from a list of compatible server binding handles.  (Client)

rpc_ns_binding_unexportRemoves the binding handles for an interface, or object UUIDs, from an entry in the name service database.  (Server)

rpc_ns_entry_expand_nameExpands the name of a name service entry.  (Client, server, or management)

rpc_ns_entry_object_inq_begin
Creates an inquiry context for viewing the objects of an entry in the name service database. (Client, server, or management)

rpc_ns_entry_object_inq_done
Deletes the inquiry context for viewing the objects of an entry in the name service database. (Client, server, or management)

rpc_ns_entry_object_inq_next
Returns one object at a time from an entry in the name service database.  (Client, server, or management)

rpc_ns_group_deleteDeletes a group attribute.  (Client, server, or management)

rpc_ns_group_mbr_addAdds an entry name to a group; if necessary, creates the entry.  (Client, server, or management)

rpc_ns_group_mbr_inq_begin
Creates an inquiry context for viewing group members.  (Client, server, or management)

rpc_ns_group_mbr_inq_done
Deletes the inquiry context for a group.  (Client, server, or management)

rpc_ns_group_mbr_inq_nextReturns one member name at a time from a group.  (Client, server, or management)

rpc_ns_group_mbr_removeRemoves an entry name from a group.  (Client, server, or management)

rpc_ns_mgmt_binding_unexport
Removes multiple binding handles, or object UUIDs, from an entry in the name service database.  (Management)

rpc_ns_mgmt_entry_createCreates an entry in the name service database.  (Management)

rpc_ns_mgmt_entry_deleteDeletes an entry from the name service database.  (Management)

rpc_ns_mgmt_entry_inq_if_ids
Returns the list of interfaces exported to an entry in the name service database. (Client, server, or management)

rpc_ns_mgmt_handle_set_exp_age
Sets a handle’s expiration age for local copies of name service data. (Client, server, or management)

rpc_ns_mgmt_inq_exp_ageReturns the application’s global expiration age for local copies of name service data.  (Client, server, or management)

rpc_ns_mgmt_set_exp_ageModifies the application’s global expiration age for local copies of name service data.  (Client, server, or management)

rpc_ns_profile_deleteDeletes a profile attribute.  (Client, server, or management)

rpc_ns_profile_elt_addAdds an element to a profile. If necessary, creates the entry.  (Client, server, or management)

rpc_ns_profile_elt_inq_begin
Creates an inquiry context for viewing the elements in a profile. (Client, server, or management)

rpc_ns_profile_elt_inq_doneDeletes the inquiry context for a profile.  (Client, server, or management)

rpc_ns_profile_elt_inq_nextReturns one element at a time from a profile.  (Client, server, or management)

rpc_ns_profile_elt_removeRemoves an element from a profile.  (Client, server, or management)

rpc_object_inq_typeReturns the type of an object.  (Server)

rpc_object_set_inq_fnRegisters an object inquiry function.  (Server)

rpc_object_set_typeAssigns the type of an object.  (Server)

rpc_protseq_vector_freeFrees the memory used by a vector and its protocol sequences.  (Client or server)

rpc_server_inq_bindingsReturns binding handles for communication with a server.  (Server)

rpc_server_inq_ifReturns the manager entry point vector registered for an interface.  (Server)

rpc_server_listenTells the RPC runtime to listen for remote procedure calls.  (Server)

rpc_server_register_auth_info
Registers authentication information with the RPC runtime.  (Server)

rpc_server_register_ifRegisters an interface with the RPC runtime.  (Server)

rpc_server_unregister_ifUnregisters an interface from the RPC runtime.  (Server)

rpc_server_use_all_protseqsTells the RPC runtime to use all supported protocol sequences for receiving remote procedure calls.  (Server)

rpc_server_use_all_protseqs_if
Tells the RPC runtime to use all the protocol sequences and endpoints specified in the interface specification for receiving remote procedure calls.  (Server)

rpc_server_use_protseqTells the RPC runtime to use the specified protocol sequence for receiving remote procedure calls.  (Server)

rpc_server_use_protseq_epTells the RPC runtime to use the specified protocol sequence combined with the specified endpoint for receiving remote procedure calls.  (Server)

rpc_server_use_protseq_ifTells the RPC runtime to use the specified protocol sequence combined with the endpoints in the interface specification for receiving remote procedure calls.  (Server)

rpc_string_binding_composeCombines the components of a string binding into a string binding.  (Client or server)

rpc_string_binding_parseReturns, as separate strings, the components of a string binding.  (Client or server)

rpc_string_freeFrees a character string allocated by the runtime.  (Client, server, or management)

uuid_compareCompares two UUIDs and determines their order.  (Client, server, or management)

uuid_createCreates a new UUID.  (Client, server, or management)

uuid_create_nilCreates a nil UUID.  (Client, server, or management)

uuid_equalDetermines if two UUIDs are equal.  (Client, server, or management)

uuid_from_stringConverts a string UUID to its binary representation.  (Client, server, or management)

uuid_hashCreates a hash value for a UUID.  (Client, server, or management)

uuid_is_nilDetermines if a UUID is nil.  (Client, server, or management)

uuid_to_stringConverts a UUID from a binary representation to a string representation.  (Client, server, or management)

ENVIRONMENT VARIABLES

The RPC name service interface (NSI) routines use the following environment variables:

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

       •RPC_DEFAULT_ENTRY Designates the default entry in the name service database that the import and lookup routines use as the starting point to search for binding information for a compatible server. Normally, the starting entry is a profile. An application that uses a default entry name must define this environment variable.  The RPC runtime does not provide a default. For example, suppose that a client application needs to search the name service database for a server binding handle.  The application can use the rpc_ns_binding_import_begin routine as part of the search.  If so, the application must specify, to the routine’s entry_name argument, the name of the entry in the name service database at which to begin the search. 

       •RPC_DEFAULT_ENTRY_SYNTAX Specifies the syntax of the name provided in the RPC_DEFAULT_ENTRY environment variable.  In addition, provides the syntax for those RPC NSI routines that allow a default value for the name syntax argument.  If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not defined, the RPC runtime uses the rpc_c_ns_syntax_dce name syntax.  See the table of valid name syntaxes in this reference page for the valid syntax values. The location of the table is in the description of the frequently used routine argument name_syntax. 

       •RPC_DEBUG Appears here for the sole purpose of telling you not to set it and not to use it.

Optionally, each application defines either or both of the first two environment variables.  The application can change the value of either one, or both, at any time during runtime. 

RPC DATA TYPES AND STRUCTURES

This section contains the data types and structures used by client, server, and management application programs. 

Much of the information in this section is derived from the NCS 2.0 Programmer’s Guide.  You may want to refer to the Guide as you read this section.  For example, this section contains a brief description of a binding handle.  The NCS 2.0 Programmer’s Guide explains binding handles in detail.  It also explains concepts related to binding handles, such as binding information and string bindings. 

Binding Handle

A binding handle is a pointer-size opaque variable containing information the RPC runtime uses to manage binding information. The RPC runtime uses binding information to establish a client-server relationship that allows the execution of remote procedure calls. 

Based on the context where it is created, a binding handle is considered a server binding handle or a client binding handle. 

A server binding handle is a reference to the binding information necessary for a client to establish a relationship with a specific server.  Many RPC API runtime routines return a server binding handle which you can use to make a remote procedure call. 

A server binding handle refers to several components of binding information.  One is the network address of a server’s host system.  Each server instance has one or more transport addresses (endpoints).  A well-known endpoint is a stable address on the host, while a dynamic endpoint is an address that the RPC runtime requests for the server.  Some transport protocols provide fewer well-known endpoints than dynamic endpoints. 

If binding information contains an endpoint, the corresponding binding handle is fully bound.  If the information lacks an endpoint, the binding handle is partially bound. 

The RPC runtime creates and provides a client binding handle to a called remote procedure as the handle_t parameter.  The client binding handle contains information about the calling client.  A client binding handle cannot be used to make a remote procedure call.  A server uses the client binding handle.  The rpc_binding_server_from_client routine converts a client binding handle to a server binding handle.  You can use the resulting server binding handle to make a remote procedure call. 

For an explanation of making a remote procedure call with a partially bound binding handle, see the NCS 2.0 Programmer’s Guide. 

Binding information can contain an object UUID.  The default object UUID associated with a binding handle is a nil UUID.  Clients can obtain a non-nil UUID in various ways, such as from a string representation of binding information (a string binding), or by importing it. 

The following table contains the RPC runtime routines that operate on binding handles.  The table also specifies the type of binding handle, client or server, allowed. 

Table 0-0.  Client and Server Binding Handles

Routine	Input Argument	Output Argument
rpc_binding_copy	server	server
rpc_binding_free	server	none
rpc_binding_from_string_binding	none	server
rpc_binding_inq_auth_client	client	none
rpc_binding_inq_auth_info	server	none
rpc_binding_inq_object	server or client	none
rpc_binding_reset	server	none
rpc_binding_server_from_client	client	server
rpc_binding_set_auth_info	server	none
rpc_binding_set_object	server	none
rpc_binding_to_string_binding	server or client	none
rpc_binding_vector_free	server	none
rpc_ns_binding_export	server	none
rpc_ns_binding_import_next	none	server
rpc_ns_binding_inq_entry_name	server	none
rpc_ns_binding_lookup_next	none	server
rpc_ns_binding_select	server	server
rpc_server_inq_bindings	none	server

If the input argument type is only a client or only a server, the routines return the status code rpc_s_wrong_kind_of_binding when an application provides the incorrect binding handle type. 

An application can share a single binding handle across multiple threads of execution.  The RPC runtime, instead of the application, manages binding handle concurrency control across concurrent remote procedure calls that use a single binding handle.  However, the client application has responsibility for binding handle concurrency control for operations that read or modify a binding handle.  The related routines are as follows:

       •rpc_binding_free

       •rpc_binding_reset

       •rpc_binding_set_auth_info

       •rpc_binding_set_object

       •rpc_ep_resolve_binding

       •rpc_mgmt_set_com_timeout

For example, suppose an application shares a binding handle across two threads of execution and it resets the binding handle endpoint in one of the threads (by calling routine rpc_binding_reset).  The binding handle in the other thread is then also reset.  Similarly, freeing the binding handle in one thread (by calling routine rpc_binding_free) frees the binding handle in the other thread. 

If you do not want this effect, your application can create a copy of a binding handle by calling routine rpc_binding_copy.  An operation on one binding handle then has no effect on the second binding handle. 

Clients and servers can access and set object UUIDs using the rpc_binding_inq_object and rpc_binding_set_object routines. 

Routines requiring a binding handle as an argument show a data type of rpc_binding_handle_t.  Binding handle arguments are passed by value. 

Binding Vector

The binding vector data structure contains a list of binding handles over which a server application can receive remote procedure calls. 

The binding vector contains a count member (count), followed by an array of binding handle (binding_h) elements. 

The C language representation of a binding vector is as follows:

typedef struct {
               unsigned32    count;
               rpc_binding_handle_t  binding_h[1];
               } rpc_binding_vector_t;

The RPC runtime creates binding handles when a server application registers protocol sequences. To obtain a binding vector, a server application calls the rpc_server_inq_bindings routine. 

A client application obtains a binding vector of compatible servers from the name service database by calling the rpc_ns_binding_lookup_next routine. 

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

In both routines, the RPC runtime allocates memory for the binding vector. An application calls the rpc_binding_vector_free routine to free the binding vector. 

To remove an individual binding handle from the vector, set its value in the vector to NULL. When setting a vector element to NULL the application must do the following:

       •Free the individual binding when it is done with it

       •Do not change the value of count before calling routine rpc_binding_vector_free

Calling the rpc_binding_free routine allows an application to free the unwanted binding handle and to set the vector entry to NULL. 

The following routines require a binding vector and show an argument data type of rpc_binding_vector_t:

       •rpc_binding_vector_free

       •rpc_ep_register

       •rpc_ep_register_no_replace

       •rpc_ep_unregister

       •rpc_ns_binding_export

       •rpc_ns_binding_lookup_next

       •rpc_ns_binding_select

       •rpc_server_inq_bindings

Boolean

Routines that require a Boolean-valued argument or return a Boolean value show a data type of boolean32. RPC provides the integer constants true (1) and false (0) for use as Boolean values. 

Endpoint Map Inquiry Handle

An endpoint map inquiry handle is a pointer-size opaque variable containing information the RPC runtime uses to access the elements in a local or remote endpoint map.  The description of the rpc_ep_register routine lists the contents of an element. 

The following routines require an endpoint map inquiry handle and show an argument data type of rpc_ep_inq_handle_t:

       •rpc_mgmt_ep_elt_inq_begin

       •rpc_mgmt_ep_elt_inq_done

       •rpc_mgmt_ep_elt_inq_next

Global Name

The Name Service Interface (NSI) uses global names for the names of name service entries.  A global name includes both a cell name and a cell-relative name composed of a directory pathname and a leaf name.  (For a description of global names, see the NSI usage chapter of the NCS 2.0 Programmer’s Guide).  The cell name is assigned to a cell root at its creation.  When you specify only a cell-relative name to an NSI operation, the NSI automatically expands the name into a global name by inserting the local cell name.  Thus, the name of a member in a group or in a profile element is always stored as a global name.  When returning the name of a name service entry or a member, NSI operations return global names. 

For example, even when you specify a cell-relative name as the member_name argument to routine rpc_ns_group_mbr_add, when you read that group member (by calling routine rpc_ns_group_mbr_inq_next), you will receive the corresponding global name. 

Interface Handle and Specification

An interface handle is a pointer-size opaque variable containing information the RPC runtime uses to access the interface specification data structure. 

The IDL compiler automatically creates an interface specification data structure from each IDL file and creates a global variable of type rpc_if_handle_t for the interface specification. 

The IDL compiler places an interface handle declaration in the generated interface-name.h file.  The compiler generates this include file for each interface. 

Routines requiring the interface handle as an argument show a data type of rpc_if_handle_t. 

The form of each interface handle name is as follows:

       •For the client: if-name_vmajor-version_minor-version_c_ifspec

       •For the server: if-name_vmajor-version_minor-version_s_ifspec

where

       •if-name is the interface identifier specified in the IDL file. 

       •major-version is the interface’s major-version number specified in the IDL file. 

       •minor-version is the interface’s minor-version number specified in the IDL file. 

An example is notes_v1_2_c_ifspec

The maximum combined length of the interface identifier and interface version number is 19 characters. 

Since the major-version and minor-version numbers must each be at least 1 character, the interface name can be no more than 17 characters.  This limits the interface handle name to 31 or fewer characters. 

No concurrency control is required for interface handles. 

The following routines require an interface handle and show an argument data type of rpc_if_handle_t:

       •rpc_ep_register

       •rpc_ep_register_no_replace

       •rpc_ep_resolve_binding

       •rpc_ep_unregister

       •rpc_if_inq_id

       •rpc_ns_binding_export

       •rpc_ns_binding_import_begin

       •rpc_ns_binding_lookup_begin

       •rpc_ns_binding_unexport

       •rpc_server_inq_if

       •rpc_server_register_if

       •rpc_server_unregister_if

       •rpc_server_use_all_protseqs_if

       •rpc_server_use_protseq_if

       •rpc_ss_register_auth_info

Interface Identifier

The interface identifier (id) data structure contains the interface UUID and major- and minor-version numbers of an interface.  The interface identifier is a subset of the data contained in the interface specification structure. 

The C language representation of an interface identifier structure is as follows:

typedef struct {
               uuid_t      uuid;
               unsigned16  vers_major;
               unsigned16  vers_minor;
               } rpc_if_id_t;

Routines that require an interface identifier structure show a data type of rpc_if_id_t. In those routines, the application is responsible for providing memory for the structure. 

The rpc_if_inq_id routine returns the interface identifier from an interface specification.  Other routines requiring an interface identifier include the following:

       •rpc_mgmt_ep_elt_inq_begin

       •rpc_mgmt_ep_elt_inq_next

       •rpc_mgmt_ep_unregister

       •rpc_ns_mgmt_binding_unexport

       •rpc_ns_profile_elt_add

       •rpc_ns_profile_elt_inq_begin

       •rpc_ns_profile_elt_inq_next

       •rpc_ns_profile_elt_remove

Interface Identifier Vector

The interface identifier (id) vector data structure contains a list of interfaces offered by a server.  The interface id vector contains a count member (count), followed by an array of pointers to interface ids (rpc_if_id_t). 

The C language representation of an interface identifier vector is as follows:

typedef struct {
               unsigned32     count;
               rpc_if_id_t    ∗if_id[1];
               } rpc_if_id_vector_t;

The interface id vector is a read-only vector.  To obtain a vector of the interface ids registered by a server with the RPC runtime, an application calls the rpc_mgmt_inq_if_ids routine.  To obtain a vector of the interface ids exported by a server to a name service database, an application calls the rpc_ns_mgmt_entry_inq_if_ids routine. 

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

The RPC runtime allocates memory for the interface id vector. The application calls the rpc_if_id_vector_free routine to free the interface id vector. 

Manager Entry Point Vector

The manager Entry Point Vector (EPV) is an array of pointers to remote procedures. 

The IDL compiler automatically generates a manager EPV data type, into the header file generated by the IDL compiler, for use in constructing manager EPVs. The data type is named as follows:

if-name_vmajor-version_minor-version_epv_t

where

       •if-name is the interface identifier specified in the IDL file. 

       •major-version is the interface’s major version number specified in the IDL file. 

       •minor-version is the interface’s minor version number specified in the IDL file. 

By default, the IDL compiler automatically creates and initializes a manager EPV.  IDL creates this EPV assuming that a manager routine of the same name exists for each procedure in the interface (as specified in the IDL file). 

The IDL compiler can define a client Entry Point Vector with addresses of local routines.  Client applications can call these routines.  For more information about client entry point vectors, see the explanation of the -cepv argument in the idl(1rpc) reference page. 

If the server offers multiple implementations of the same interface, the server must create additional manager EPVs, one for each implementation. Each EPV must contain exactly one entry point (address of a function) for each procedure defined in the IDL file. The server application declares and initializes one manager EPV variable of type if-name_vmajor-version_minor-version_epv_t for each implementation of the interface. 

The rpc_server_register_if and rpc_server_inq_if routines use the manager EPV data type and show the manager EPV argument as having an rpc_mgr_epv_t data type. 

Name Service Handle

A name service handle is a pointer-size opaque variable containing information the RPC runtime uses to return the following RPC data from the name service database:

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

       •server binding handles

       •UUIDs of resources offered by a server

       •profile members

       •group members

The following routines require a name service handle and show an argument data type of rpc_ns_handle_t:

       •rpc_ns_binding_import_begin

       •rpc_ns_binding_import_next

       •rpc_ns_binding_import_done

       •rpc_ns_binding_lookup_begin

       •rpc_ns_binding_lookup_next

       •rpc_ns_binding_lookup_done

       •rpc_ns_entry_object_inq_begin

       •rpc_ns_entry_object_inq_next

       •rpc_ns_entry_object_inq_done

       •rpc_ns_group_mbr_inq_begin

       •rpc_ns_group_mbr_inq_next

       •rpc_ns_group_mbr_inq_done

       •rpc_ns_profile_elt_inq_begin

       •rpc_ns_profile_elt_inq_next

       •rpc_ns_profile_elt_inq_done

       •rpc_ns_mgmt_handle_set_exp_age

The scope of a name service handle is from a ∗_begin routine through the corresponding ∗_done routine. 

Applications have responsibility for concurrency control of name service handles across threads. 

Protocol Sequence

A protocol sequence is a character string identifying the network protocols used to establish a relationship between a client and server.  The protocol sequence contains a set of options that the RPC runtime must know about.  The following options are in this set:

       •The RPC protocol used for communications (choices are ncacn and ncadg). 

       •The format used in the network address supplied in the binding (choice is ip). 

       •The transport protocol used for communications (choices are tcp and udp). 

Because only certain combinations of these options are valid (are useful for interoperation), RPC provides predefined strings that represent the valid combinations.  RPC applications use only these strings. 

The following table contains predefined strings representing valid protocol sequences.  In the descriptions NCA is an abbreviation of Network Computing Architecture. 

Table 0-0.  Valid Protocol Sequences

Protocol SequenceDescription

ncacn_ip_tcpNCA Connection over Internet Protocol: Transmission Control Protocol

ip or ncadg_ip_udpNCA Datagram over Internet Protocol: User Datagram Protocol

A server application can use a particular protocol sequence only if the operating system software supports that protocol.  A server chooses to accept remote procedure calls over some or all of the supported protocol sequences. 

Client and server applications can determine if a protocol sequence is supported by both the RPC runtime and the operating system.  The applications make this determination by calling the following routines:

       •rpc_network_inq_protseqs

       •rpc_network_is_protseq_valid

The following routines allow server applications to register protocol sequences with the runtime:

       •rpc_server_use_all_protseqs

       •rpc_server_use_all_protseqs_if

       •rpc_server_use_protseq

       •rpc_server_use_protseq_ep

       •rpc_server_use_protseq_if

Those routines requiring a protocol sequence argument show a data type of unsigned_char_t ∗. 

A client can use the protocol sequence strings to construct a string binding using the rpc_string_binding_compose routine. 

Protocol Sequence Vector

The protocol sequence vector data structure contains a list of protocol sequences over which the RPC runtime can send or receive remote procedure calls.  The protocol sequence vector contains a count member (count), followed by an array of pointers to protocol sequence strings (protseq). 

The C language representation of a protocol sequence vector is as follows:

typedef struct {
               unsigned32       count;
               unsigned_char_t  ∗protseq[1];
               } rpc_protseq_vector_t;

The protocol sequence vector is a read-only vector.  To obtain a protocol sequence vector, a server application calls the rpc_network_inq_protseqs routine. The RPC runtime allocates memory for the protocol sequence vector. The server application calls the rpc_protseq_vector_free routine to free the protocol sequence vector. 

Statistics Vector

The statistics vector data structure contains statistics from the RPC runtime on a per address space basis.  The statistics vector contains a count member (count), followed by an array of statistics.  Each array element contains an unsigned32 value. The following list describes the statistics indexed by the specified constant:

rpc_c_stats_calls_inThe number of remote procedure calls received by the runtime

rpc_c_stats_calls_outThe number of remote procedure calls initiated by the runtime

rpc_c_stats_pkts_inThe number of network packets received by the runtime

rpc_c_stats_pkts_outThe number of network packets sent by the runtime

The C language representation of a statistics vector is as follows:

typedef struct {
               unsigned32       count;
               unsigned32       stats[1];
               } rpc_stats_vector_t;

To obtain runtime statistics, an application calls the rpc_mgmt_inq_stats routine. The RPC runtime allocates memory for the statistics vector. The application calls the rpc_mgmt_stats_vector_free routine to free the statistics vector. 

String Binding

A string binding contains the character representation of a binding handle. 

String bindings are a convenient way of representing portions of a binding handle.  However, you cannot use string bindings directly to make remote procedure calls.  You must first call the routine rpc_binding_from_string_binding which converts a string binding to a binding handle. 

A string binding does not contain all the information from a binding handle.  For example, a call to the routine rpc_binding_to_string_binding does not translate the authentication information sometimes associated with a binding handle into the resulting string binding. 

NOTE:

For this release, the RPC authentication (RPC auth) routines are not implemented, nor is an independent security service provided. 

You can begin the development of a distributed application by having its servers communicate their binding information to clients by using string bindings. This communication allows a server to establish a client-server relationship without using the local endpoint map or the name service database. 

In this case, the server calls none of the routines rpc_ep_register, rpc_ep_register_no_replace, and rpc_ns_binding_export.  Instead, the server calls only routine rpc_server_inq_bindings to obtain a vector of binding handles.  The server obtains binding handles one at a time from the vector and calls routine rpc_binding_to_string_binding to convert each binding handle into a string binding.  The resulting string binding is always fully bound and may contain a non-nil object UUID. The server then makes some or all of its string bindings available to clients.  One way is placing the string bindings in a file to be read by clients or users or both.  Another way is delivering the string bindings to clients or users by means of a file, mail, or paper. 

You can continue the distributed application’s development by changing the application so that servers use the local endpoint map and the name service database to communicate their binding information. 

To find the server, a client obtains a string binding containing a protocol sequence that the client runtime supports and, optionally, an object UUID that the client requires.  The client then calls routine rpc_binding_from_string_binding to convert the string binding into a server binding handle. 

Other useful routines for working with string bindings are rpc_string_binding_compose, which creates a string binding from its component parts, and rpc_string_binding_parse, which separates a string binding into its component parts. 

The two formats of a string binding follow. The four fields represent the object UUID, RPC protocol sequence, network address, and endpoint and network options of the binding.  A delimiter character such as @ (at sign) or : (colon) separates each field.  A string binding does not contain any white space. 

object-uuid @ rpc-protocol-sequence : nw-addr [endpoint , option ...]

or

object-uuid @ rpc-protocol-sequence : nw-addr [endpoint = endpoint , option ... ]

object-uuidThis field specifies the UUID of the object operated on by the remote procedure that is called with this string binding.  The RPC runtime, at the server, maps the object’s type to a manager entry point vector (EPV) to invoke the correct manager routine.  The explanation of the routine rpc_server_register_if discusses mapping object UUIDs to manager EPVs.  This field is optional.  If you do not provide it the RPC runtime assumes a nil UUID.

@This symbol is the delimiter character for the object UUID field.  If you specify an object UUID you must follow it with this symbol. 

rpc-protocol-sequenceThis field specifies the protocol sequence used for making remote procedure calls.  The valid protocol sequences are as follows:

       •ncacn_ip_tcp

       •ncadg_ip_udp

More information about these valid protocol sequences appears in a table in the description of a protocol sequence in this introduction reference page.  This field is required.

:This symbol is the delimiter character for the RPC protocol sequence field. 

nw-addrThis field specifies the address (addr) of a host on a network (nw) that receives remote procedure calls made with this string binding.  The format and content of the network address depends on the value of rpc-protocol-sequence as follows:

       •ncacn_ip_tcp and ncadg_ip_udp Specify an Internet address using the common Internet address notation or host name. Two examples with common Internet address notation are 128.10.2.30 and #126.15.1.28.  The second example shows the use of the optional # (number sign) character.  An example with a host name is ko If the specified host name is multihomed, the binding handle returned from routine rpc_binding_from_string_binding contains a host address.  It is the first host address returned from the system library call that translates a host name to a host address for the network address format in the protocol sequence.  To control the host address used, specify the network address using the common Internet address notation instead of a host name. 

The network address field is optional.  If you do not supply this field, the string binding refers to your local host. 

[This symbol is the delimiter character specifying that one endpoint and zero or more options follow.  If the string binding contains at least one endpoint, this symbol is required. 

endpointThis field specifies the endpoint, or address of a specific server instance on a host, to receive remote procedure calls made with this string binding.  Optionally the keyword endpoint= can precede the endpoint specifier.  The format and content of the endpoint depends on the specified protocol sequence as follows:

       •ncacn_ip_tcp and ncadg_ip_udp Specify an Internet port number. An example of an Internet port number is 1025

The endpoint field is optional.  For more information about endpoints, see the section about binding handles in this reference page. 

,This symbol is the delimiter character specifying that option data follows.  If an option follows, this delimiter is required. 

optionThis field specifies any options.  Each option is specified as option name=option value.  The format and content of the option depends on the specified protocol sequence as follows:

       •ncacn_ip_tcp and ncadg_ip_udp There are no Internet options.

The option field is optional. 

]This symbol is the delimiter character specifying that one endpoint and zero or more options precede.  If the string binding contains at least one endpoint, this symbol is required. 

The backslash character (\) is treated as an escape character for all string binding fields. 

Examples of valid string bindings follow.  In each example obj-uuid represents a UUID in string form.  In other words, the symbol obj-uuid can represent the UUID 308FB580-1EB2-11CA-923B-08002B1075A7. 

 obj-uuid@ncacn_ip_tcp:16.20.16.27[2001]
obj-uuid@ncacn_ip_tcp:16.20.16.27[endpoint=2001]

String UUID

A string UUID contains the character representation of a UUID.  A string UUID consists of multiple fields of hexadecimal characters.  Each field has a fixed length, and hyphens separate the fields.  An example of a string UUID follows. 

 989C6E5C-2CC1-11CA-A044-08002B1BB4F5

When you supply a string UUID as an input argument to an RPC runtime routine, you can enter the alphabetic hexadecimal characters in either uppercase or lowercase.  The RPC runtime routines that return a string UUID always return the hexadecimal characters in uppercase letters. 

The following routines require a string UUID:

       •rpc_string_binding_compose

       •rpc_string_binding_parse

       •uuid_from_string

       •uuid_to_string

Unsigned Character String

NCS 2.0 RPC treats all characters in strings as unsigned characters. Those routines with character string arguments show a data type of unsigned_char_t ∗. 

UUID Vector

The UUID vector data structure contains a list of UUIDs.  The UUID vector contains a count member (count), followed by an array of pointers to UUIDs. 

The C language representation of a UUID vector is as follows:

typedef struct
{
    unsigned32    count;
    uuid_t        ∗uuid[1];
} uuid_vector_t;

An application constructs a UUID vector to contain object UUIDs to be exported or unexported from the name service database. The following routines require a UUID vector and show an argument data type of uuid_vector_t:

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

       •rpc_ep_register

       •rpc_ep_register_no_replace

       •rpc_ep_unregister

       •rpc_ns_binding_export

       •rpc_ns_binding_unexport

       •rpc_ns_mgmt_binding_unexport

PERMISSIONS REQUIRED

To use the Name Service Interface (NSI) routines to access entries in a Cell Directory Service (CDS) database, you need access control list (ACL) permissions.  Depending on the NSI operation, you need ACL permissions to the parent directory or the CDS object entry (the name service entry) or both.  The ACL permissions are as follows:

       •To create an entry, you need insert permission to the parent directory. 

       •To read an entry, you need read permission to the CDS object entry. 

       •To write to an entry, you need write permission to the CDS object entry. 

       •To delete an entry, you need delete permission either to the CDS object entry or to the parent directory. 

       •To test an entry, you need either test permission or read permission to the CDS object entry. 

Note:  Write permission does not imply read permission. 

To find the ACL permissions for the NSI routines (whose names begin with rpc_ns), see the "Permissions Required" parts of the description sections in the routines’ reference pages. 

The non-NSI routines (whose names do not begin with rpc_ns) do not need ACL permissions, so their reference pages have no "Permissions Required" parts. 

FREQUENTLY USED ROUTINE ARGUMENTS

A few arguments are common to many of the RPC routines.  These arguments are described fully here and again briefly on the specific routine reference pages. 

binding

Used as an input or output argument. 

Returns a binding handle for making remote procedure calls to a server. 

A client obtains a binding handle by calling one of the following routines:

       •rpc_binding_copy

       •rpc_binding_from_string_binding

       •rpc_ns_binding_import_next

       •rpc_ns_binding_select

Creating a binding handle establishes a relationship between a client and a server.  However, the relationship does not involve any communication between the client and server.  The communication occurs when a client makes a remote procedure call. 

As an input argument to a remote procedure call, binding specifies a binding handle that refers to binding information.  The client’s RPC runtime uses this binding information to make a remote procedure call to a server. 

Server manager routines can extract client information from a client binding handle by using the following routines:

       •rpc_binding_inq_auth_client

       •rpc_binding_inq_object

       •rpc_binding_to_string_binding

       •rpc_string_binding_parse

name

Used as an input/output argument. 

When used as an input argument, the value of this argument depends on the syntax selected in the name_syntax argument. If it is allowed by the called routine, the value NULL specifies that the routine uses the name specified in the RPC_DEFAULT_ENTRY environment variable. 

For a name_syntax value of rpc_c_ns_syntax_dce, use the naming rules to specify argument name. 

As an output argument, returns an entry in the name service database in the form of a character string that includes a terminating null character. The value of this argument depends on the syntax selected in name_syntax. 

For a name_syntax value of rpc_c_ns_syntax_dce, name is returned using the naming syntax. 

The RPC runtime allocates memory for the returned string. The application is responsible for calling the rpc_string_free routine to deallocate the string. 

If an application does not want a returned name string, the application usually specifies NULL for this argument.  The one exception is routine rpc_ns_entry_expand_name; it always returns a name string. 

name_syntax

Used as an input argument, an integer value that specifies the syntax of an entry name. When allowed by the called routine, a value of rpc_c_ns_syntax_default specifies that the routine uses the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX environment variable.  The following table lists the valid syntaxes that applications can use in RPC, for entries in the name service database:

NOTE:

For this release, the RPC naming service (rpc_ns) routines are not implemented, nor is an independent naming service provided. 

Table 0-0.  Valid Name Syntaxes

Constant	Value	Description
rpc_c_ns_syntax_default	0	Default syntax
rpc_c_ns_syntax_dce	3	DCE

The name_syntax argument tells routines how to parse the entry name specified in an input name argument or specifies the syntax to use when returning an entry name as an output name argument. 

If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not defined, the RPC runtime uses the rpc_c_ns_syntax_dce name syntax. 

string

Used as an input or output argument. 

Returns a character string, which always includes the terminating null character \0.  The RPC runtime allocates memory for the returned string. The application calls the rpc_string_free routine to deallocate the memory occupied by the string. 

If there is no data for the requested string, the routine returns the string \0.  For example, if the string binding passed to routine rpc_string_binding_parse does not contain an object UUID, the routine returns \0 as the value of the object UUID string.  The application must call the rpc_string_free routine to deallocate the memory occupied by this string. 

If an application does not require a returned output string, the application specifies NULL for this argument. 

status

Each routine in the RPC API returns a status code indicating whether the routine completed successfully or, if not, why not.  A return value of rpc_s_ok indicates success.  All other return values signify routine failure.  The status codes listed for each RPC runtime routine are the most likely, but not necessarily all, the status codes that the routine can return. 

The status code argument has a data type of unsigned32. 

To translate a status code to a text message, call the routine dce_error_inq_text. 

Note: RPC exceptions are equivalent to RPC status codes.  To identify the status code that corresponds to a given exception, replace the _x_ string of the exception with the string _s_; for example, the exception rpc_x_already_listening is equivalent to the status code rpc_s_already_listening. 

uuid

Used as an input or output argument. 

When you need to specify a nil UUID to a uuid input argument in any of the RPC routines, you can supply the value NULL.