The Remote Procedure Call (RPC) service provides connections between individual procedures in an application across heterogeneous systems in a transparent way.
1 – Application Commands
NAME
rpc_intro - Introduction to the DCE RPC programmer commands
DESCRIPTION
DCE RPC provides the following programmer commands:
+ The idl command invokes the Interface Definition Language
(IDL) compiler to convert an interface definition, written
in IDL, to output files.
+ The uuidgen command creates a UUID string that you assign to
an object to uniquely distinguish it from other objects.
See each command's reference page for further information.
IDL Base Data Types and IDL-to-C
The following 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.
Base Data Type Specifiers - rpc_intro
___________________________________________________________
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.
RELATED INFORMATION
Commands: idl
uuidgen
Messages: OSF DCE Problem Determination Guide.
Books: OSF DCE Application Development Guide.
2 – API Runtime Intro
NAME
rpc_intro - Introduction to the DCE RPC API runtime
DESCRIPTION
This introduction gives general information about the DCE RPC
Application Programming Interface (API) and an overview of the
following parts of the DCE RPC API runtime:
+ Runtime services
+ Environment variables
+ Data types and structures
+ Permissions required
+ Frequently used routine arguments
2.1 – General Information
The following subsections contain 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 rpc_intro reference
page in the OSF DCE Command Reference contains a summary of the
idl command, which invokes the IDL compiler.
Additional information about the IDL compiler appears in the
following table, which shows the IDL base types and the IDL-to-C
mappings. The following 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.
Base Data Type Specifiers - rpc_intro
___________________________________________________________
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
SYS$COMMON:[DCE$LIBRARY]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, DCE RPC provides
two management commands for the RPC control program and the DCE
Host daemon, as follows:
+ The rpccp control program 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.
You can manage the name service with RPCCP commands or with DCE
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
following DCE RPC runtime routines:
- rpc_ns_group_mbr_inq_begin()
- rpc_ns_group_mbr_inq_next()
- rpc_ns_group_mbr_inq_done()
+ The dced command starts the DCE Host daemon. The daemon
maintains the local endpoint map for RPC servers and looks
up endpoints for RPC clients.
See the OSF DCE Administration Reference for more information about
these two management commands.
2.2 – Overview of DCE RPC Runtime Services
The RPC runtime services consist of RPC routines that perform a
variety of operations.
Note that 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. For more information about threads and
their cancellation, see the OSF DCE Application Development Guide -
Core Components.
The rest of this overview consists of the following items:
+ An explanation of abbreviations in the names of the RPC runtime
routines
+ An alphabetical list of DCE RPC runtime routines. With each
routine name is its description and the type of application
program that most likely calls the routine.
An alphabetical list of abbreviations in the names of the DCE RPC
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)."
auth - authentication, authorization
com - communications
cs - character/code set interoperability
dce - distributed computing environment
dflt - default
elt - element
ep - endpoint
exp - expiration
fn - function
id - identifier
idl_es - IDL encoding services
if - interface
inq - inquiry
mbr - member
mgmt - management
ns - name service
protseq - protocol sequence
rgy - DCE character and code set registry
rpc - remote procedure call
stats - statistics
An alphabetical list of the RPC runtime routines follows. With each
routine name is its description and the type of application program
that most likely calls the routine.
cs_byte_from_netcs()
Converts international character data from a network code set
to a local code set. (Client, server).
cs_byte_local_size()
Calculates the necessary buffer size for a code set conversion
from a network code set to a local code set. (Client, server).
cs_byte_net_size()
Calculates the necessary buffer size for a code set conversion
from a local code set to a network code set. (Client, server).
cs_byte_to_netcs()
Converts international character data from a local code set to a
network code set. (Client, server).
dce_cs_loc_to_rgy()
Maps a local name for a code set to a code set value in the code
set registry. (Client, server).
dce_cs_rgy_to_loc()
Maps a code set value in the code set registry to a the local
name for a code set. (Client, server).
idl_es_decode_buffer()
Returns a buffer decoding handle. (Client, server).
idl_es_decode_incremental()
Returns an incremental decoding handle. (Client, server).
idl_es_encode_dyn_buffer()
Returns a dynamic buffer encoding handle. (Client, server).
idl_es_encode_fixed_buffer()
Returns a fixed buffer encoding handle. (Client, server).
idl_es_encode_incremental()
Returns an incremental encoding handle. (Client, server).
idl_es_handle_free()
Frees an IDL encoding services handle. (Client, server).
idl_es_inq_encoding_id()
Identifies an application encoding operation. (Client, server).
rpc_binding_copy()
Returns a copy of a binding handle. (Client or server).
rpc_binding_free()
Releases 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_client()
Returns authentication and authorization information from the
binding handle for an authenticated client. (Server).
rpc_binding_inq_auth_info()
Returns authentication and authorization information from a
server binding handle. (Client).
rpc_binding_inq_object()
Returns the object UUID from a binding handle. (Client or server).
rpc_binding_reset()
Resets 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_info()
Sets authentication and authorization information into a server
binding handle. (Client).
rpc_binding_set_object()
Sets 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_free()
Frees the memory used to store a vector and binding handles.
(Client or server).
rpc_cs_binding_set_tags()
Places code set tags into a server binding handle. (Client).
rpc_cs_char_set_compat_check()
Evaluates character set compatibility between a client and a
server. (Client).
rpc_cs_eval_with_universal()
Evaluates a server's supported character sets and code sets during
the server binding selection process. (Client).
rpc_cs_eval_without_universal()
Evaluates a server's supported character sets and code sets during
the server binding selection process. (Client).
rpc_cs_get_tags()
Retrieves code set tags from a binding handle. (Client, server).
rpc_ep_register()
Adds to, or replaces, server address information in the local
endpoint map. (Server).
rpc_ep_register_no_replace()
Adds to server address information in the local endpoint map.
(Server).
rpc_ep_resolve_binding()
Resolves a partially bound server binding handle into a fully
bound server binding handle. (Client or management).
rpc_ep_unregister()
Removes server address information from the local endpoint map.
(Server).
rpc_if_id_vector_free()
Frees a vector and the interface identifier structures it
contains. (Client, server, or management).
rpc_if_inq_id()
Returns the interface identifier for an interface specification.
(Client or server).
rpc_mgmt_ep_elt_inq_begin()
Creates an inquiry context for viewing the elements in a local
or remote endpoint map. (Management).
rpc_mgmt_ep_elt_inq_done()
Deletes the inquiry context for viewing the elements in a local
or remote endpoint map. (Management).
rpc_mgmt_ep_elt_inq_next()
Returns one element at a time from a local or remote endpoint
map. (Management).
rpc_mgmt_ep_unregister()
Removes server address information from a local or remote
endpoint map. (Management).
rpc_mgmt_inq_com_timeout()
Returns the communications time-out 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_ids()
Returns 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_stats()
Returns 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_timeout()
Sets the communications time-out 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_free()
Frees 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_protseqs()
Returns 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_export()
Establishes 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_done()
Deletes the import context for searching the name service
database. (Client).
rpc_ns_binding_import_next()
Returns 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_done()
Deletes the lookup context for searching the name service
database. (Client).
rpc_ns_binding_lookup_next()
Returns a list of binding handles of one or more compatible
servers (if found) from the name service database. (Client).
rpc_ns_binding_select()
Returns a binding handle from a list of compatible server binding
handles. (Client).
rpc_ns_binding_unexport()
Removes the binding handles for an interface, or object UUIDs,
from an entry in the name service database. (Server).
rpc_ns_entry_expand_name()
Expands 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_delete()
Deletes a group attribute. (Client, server, or management).
rpc_ns_group_mbr_add()
Adds 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_next()
Returns one member name at a time from a group. (Client, server,
or management).
rpc_ns_group_mbr_remove()
Removes an entry name from a group. (Client, server, or
management).
rpc_ns_import_ctx_add_eval()
Adds an evaluation routine to an import context. (Client).
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_create()
Creates an entry in the name service database. (Management).
rpc_ns_mgmt_entry_delete()
Deletes 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_free_codesets()
Frees a code sets array that has been allocated in memory.
(Client).
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_age()
Returns the application's global expiration age for local copies
of name service data. (Client, server, or management).
rpc_ns_mgmt_read_codesets()
Reads the code sets attribute associated with an RPC server
entry in the name service database. (Client).
rpc_ns_mgmt_remove_attribute()
Removes an attribute from an RPC server entry in the name
service database. (Server, management).
rpc_ns_mgmt_set_attribute()
Adds an attribute to an RPC server entry in the name service
database. (Server, management).
rpc_ns_mgmt_set_exp_age()
Modifies the application's global expiration age for local copies
of name service data. (Client, server, or management).
rpc_ns_profile_delete()
Deletes a profile attribute. (Client, server, or management).
rpc_ns_profile_elt_add()
Adds 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_done()
Deletes the inquiry context for a profile. (Client, server, or
management).
rpc_ns_profile_elt_inq_next()
Returns one element at a time from a profile. (Client, server,
or management).
rpc_ns_profile_elt_remove()
Removes an element from a profile. (Client, server, or
management).
rpc_object_inq_type()
Returns the type of an object. (Server).
rpc_object_set_inq_fn()
Registers an object inquiry function. (Server).
rpc_object_set_type()
Assigns the type of an object. (Server).
rpc_protseq_vector_free()
Frees the memory used by a vector and its protocol sequences.
(Client or server).
rpc_rgy_get_codesets()
Gets supported code sets information from the local host.
(Client, server).
rpc_rgy_get_max_bytes()
Gets the maximum number of bytes that a code set uses to encode
one character. (Client, server).
rpc_server_inq_bindings()
Returns binding handles for communication with a server.
(Server).
rpc_server_inq_if()
Returns the manager entry point vector registered for an
interface. (Server).
rpc_server_listen()
Tells 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_if()
Registers an interface with the RPC runtime. (Server).
rpc_server_unregister_if()
Unregisters an interface from the RPC runtime. (Server).
rpc_server_use_all_protseqs()
Tells the RPC runtime to use all supported protocol sequences
for receiving remote procedure calls. (Server).
rpc_set_local_float_drep()
Sets the float type in the runtime to the one with which
the application is being compiled.
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_protseq()
Tells the RPC runtime to use the specified protocol sequence
for receiving remote procedure calls. (Server).
rpc_server_use_protseq_ep()
Tells the RPC runtime to use the specified protocol sequence
combined with the specified endpoint for receiving remote
procedure calls. (Server).
rpc_server_use_protseq_if()
Tells the RPC runtime to use the specified protocol sequence
combined with the endpoints in the interface specification for
receiving remote procedure calls. (Server).
rpc_sm_allocate()
Allocates memory within the RPC stub memory management scheme.
(Usually server, possibly client).
rpc_sm_client_free()
Frees memory allocated by the current memory allocation and
freeing mechanism used by the client stubs. (Client).
rpc_sm_destroy_client_context()
Reclaims the client memory resources for a context handle, and
sets the context handle to NULL. (Client).
rpc_sm_disable_allocate()
Releases resources and allocated memory within the RPC stub
memory management scheme. (Client).
rpc_sm_enable_allocate()
Enables the stub memory management environment. (Client).
rpc_sm_free()
Frees memory allocated by the rpc_sm_allocate() routine.
(Usually server, possibly client).
rpc_sm_get_thread_handle()
Gets a thread handle for the stub memory management environment.
(Usually server, possibly client).
rpc_sm_set_client_alloc_free()
Sets the memory allocation and freeing mechanism used by the
client stubs. (Client).
rpc_sm_set_thread_handle()
Sets a thread handle for the stub memory management environment.
(Usually server, possibly client).
rpc_sm_swap_client_alloc_free()
Exchanges the current memory allocation and freeing
mechanism used by the client stubs with one supplied by
the client. (Client).
rpc_string_binding_compose()
Combines the components of a string binding into a string
binding. (Client or server).
rpc_string_binding_parse()
Returns, as separate strings, the components of a string
binding. (Client or server).
rpc_string_free()
Frees a character string allocated by the runtime. (Client,
server, or management).
uuid_compare()
Compares two UUIDs and determines their order. (Client,
server, or management).
uuid_create()
Creates a new UUID. (Client, server, or management).
uuid_create_nil()
Creates a nil UUID. (Client, server, or management).
uuid_equal()
Determines if two UUIDs are equal. (Client, server, or
management).
uuid_from_string()
Converts a string UUID to its binary representation. (Client,
server, or management).
uuid_hash()
Creates a hash value for a UUID. (Client, server, or
management).
uuid_is_nil()
Determines if a UUID is nil. (Client, server, or management).
uuid_to_string()
Converts a UUID from a binary representation to a string
representation. (Client, server, or management).
wchar_t_from_netcs()
Converts international character data from a network code set
to a local code set. (Client, server).
wchar_t_local_size()
Calculates the necessary buffer size for a code set conversion
from a network code set to a local code set. (Client, server).
wchar_t_net_size()
Calculates the necessary buffer size for a code set conversion
from a local code set to a network code set. (Client, server).
wchar_t_to_netcs()
Converts international character data from a local code set to
a net work code set. (Client, server).
2.3 – Logical Names
The RPC Name Service Interface (NSI) routines uses the following
logical names:
+ 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
logical name. 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 parameter, the name of the entry in the
name service database at which to begin the search. If the
search is to begin at the entry that the RPC_DEFAULT_ENTRY
logical name specifies, then the application must specify the
value NULL to parameter entry_name in
rpc_ns_binding_import_begin().
+ RPC_DEFAULT_ENTRY_SYNTAX
Specifies the syntax of the name provided in the
RPC_DEFAULT_ENTRY logical name. 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
logical name is not defined, the RPC runtime uses the
rpc_c_ns_syntax_dce name syntax. (For the valid name syntaxes
in this reference page and for the valid syntax values, see the
table in the description of the frequently used routine argument
name_syntax, which appears later in this reference page.)
Optionally, each application defines either or both of the first two
logical names. The application can change the value of either one,
or both, at any time during runtime.
2.4 – RPC Data Types and Structures
The following subsections contain the data types and structures used by client, server, and management application programs. Much of the information in this section is derived from the Application Development Guide. You may want to refer to this book as you read this section. For example, this section contains a brief description of a binding handle. The RPC section of the Application Development Guide explains binding handles in detail. It also explains concepts related to binding handles, such as binding information and string bindings.
2.4.1 – 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 that 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 a fully bound binding handle. If the information
lacks an endpoint, the binding handle is a partially bound binding
handle.
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 OSF DCE Application
Development Guide - Core Components. For an explanation of failures
associated with such a call, see the explanation of status code
rpc_s_wrong_boot_time in the OSF DCE Problem Determination 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.
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 rpc_binding_reset()). The binding
handle in the other thread is then also reset. Similarly, freeing
the binding handle in one thread (by calling 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 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.
2.4.2 – 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
rpc_ns_binding_lookup_next(). 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.
An application, when it is finished with an individual binding
handle in a binding vector, frees the binding handle by calling
rpc_binding_free(). This routine also sets the corresponding
pointer in the binding vector to NULL.
Note that you should not decrement the count field in a binding
vector structure when you call the rpc_binding_free() routine to
free an individual binding handle.
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()
2.4.3 – Boolean
Routines that require a Boolean-valued argument or return a Boolean value show a data type of boolean32. DCE RPC provides the integer constants TRUE (1) and FALSE (0) for use as Boolean values.
2.4.4 – Code Set
A code set is a mapping of the members of a character set to
specific numeric code values. Different code sets use different
numeric code values to represent the same character. In general,
operating systems use string names to refer to the code sets that
the system supports. It is common for different operating systems
to use different string names to refer to the same code set.
Distributed applications that run in a network of heterogeneous
operating systems need to be able to identify the character sets
and code sets that client and server machines are using to avoid
losing data during communications between each other. DCE RPC
supports transparent automatic conversion for characters that are
members of the DCE Portable Character Set (DCE PCS) and which are
encoded in the ASCII and U.S. EBCDIC code sets. The RPC runtime
automatically converts DCE PCS characters encoded in ASCII or U.S.
EBCDIC, if necessary, when they are passed over the network between
client and server.
DCE RPC applications that need to transfer character data that is
outside the DCE PCS character set and ASCII and U.S. EBCDIC
encodings (international characters) can use special IDL constructs
and a set of DCE RPC routines to set up their applications so that
they can pass this "international" character data with minimal or no
loss between client and server applications. An example of such an
application would be one that used European, Chinese, or Japanese
characters mapped to EUC, Big5, or SJIS encodings. Together, the
IDL constructs and the DCE RPC routines provide a method of
automatic code set conversion for applications that transfer
international character data in heterogeneous code set environments.
DCE provides a mechanism to uniquely identify a code set; this
mechanism is the code set registry. The code set registry assigns
a unique identifier to each character set and code set. Because
the registry provides code set identifiers that are consistent
across a network of heterogeneous operating systems, it provides a
method for clients and servers in a heterogeneous environment to
use to identify code sets without having to rely on operating
system specific string names.
The code set data structure contains a 32-bit hexadecimal value
(c_set) that uniquely identifies the code set followed by a 16-bit
decimal value (c_max_bytes) that indicates the maximum number of
bytes this code set uses to encode one character in this code set.
The value for c_set is one of the registered values in the code set
registry.
The following routines require a code set value:
+ cs_byte_from_netcs()
+ cs_byte_local_size()
+ cs_byte_net_size()
+ cs_byte_to_netcs()
+ dce_cs_loc_to_rgy()
+ dce_cs_rgy_to_loc()
+ rpc_cs_get_tags()
+ rpc_cs_binding_set_tags()
+ rpc_rgy_get_max_bytes()
+ wchar_t_from_netcs()
+ wchar_t_local_size()
+ wchar_t_net_size()
+ wchar_t_to_netcs()
In these routines, the code set value shows a data type of
unsigned32. The RPC stub buffer sizing routines *Lnet_size() and
*_local_size use the value of c_max_bytes to calculate the size of
a buffer for code set conversion.
The C language representation of a code set structure is as follows:
typedef struct {
long c_set;
short c_max_bytes;
} rpc_cs_c_set_t;
The code set data structure is a member of the code sets array.
2.4.4.1 – Code Sets Array
The code sets array contains the list of the code sets that a
client or server supports. The structure consists of a version
number member (version), followed by a count member (count),
followed by an array of code set data structures (rpc_cs_c_set_t).
This array is declared to be a conformant array so that its size
will be determined at runtime. The count member indicates the
number of code sets contained in the array. The first element in
the code sets array represents the client or server process's
local code set.
The second element through the nth element represents one or more
intermediate code sets that the process can use to transmit
character data over the network. Client or server processes can
convert into an intermediate code set when their host system does
not provide a converter for the other's local code set but does
provide a converter for the intermediate code set.
DCE RPC routines for character/code sets compatibility evaluation
and code set conversion support one intermediate code set, which
is the ISO 10646 Universal character/code set. Consequently, DCE
requires host systems running applications that transfer
international characters to provide converters for this code set.
System administrators for machines in internationalized DCE cells
(that is, cells of machines that run applications that use the DCE
character/code sets compatibility evaluation and conversion
functionality) and who want to use other intermediate code sets
can run the csrc utility and specify that their intermediate code
set(s) be used in preference to ISO 10646.
The remaining elements in the array represent other code sets that
the process's host supports (that is, code sets for which the
system provides converters).
The C language representation of a code set structure is as
follows:
typedef struct rpc_codeset_mgmt_t {
unsigned32 version;
long count;
[size_is(count)] rpc_cs_c_set_t codesets[];
} rpc_codeset_mgmt_t, *rpc_codeset_mgmt_p_t;
Client and server applications and DCE RPC routines for automatic
code set conversion obtain a code sets array by calling the
routine rpc_rgy_get_codesets(). Server applications user the code
sets array as input to the rpc_ns_mgmt_set_attribute() routine,
which registers their supported code sets in the name service
database. Client applications look up a server's supported code
sets in the name service database by calling the routine
rpc_ns_mgmt_read_codesets() and then use their code sets array to
evaluate their supported code sets against the code sets that the
server supports.
The following DCE RPC routines require a code sets array and show
an argument data type of rpc_codeset_mgmt_t:
+ rpc_ns_mgmt_read_codesets()
+ rpc_rgy_get_codesets()
Server applications that use the routine
rpc_ns_mgmt_set_attribute() to register their supported code sets
in the name service database also specify the code sets array, but
show an argument data type of void.
2.4.4.2 – Conversion Type
The conversion type data structure is an enumerated type that RPC
stub buffer sizing routines return to indicate whether character
data conversion is necessary and whether or not existing storage
is sufficient for the stub to store the results of the conversion.
The conversion type can be one of the following values:
idl_cs_no_convert
No code set conversion is required.
idl_cs_in_place_convert
Code set conversion can be performed in a single
storage area.
idl_cs_new_buffer_convert
The converted data must be written to a new
storage area.
The C language representation of a conversion type structure is as
follows:
typedef enum {
idl_cs_no_convert,
idl_cs_in_place_convert,
idl_cs_new_buffer_convert,
} idl_cs_convert_t;
2.4.5 – 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()
2.4.6 – 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 OSF DCE Administration 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 parameter to routine rpc_ns_group_mbr_add(), when you read that group member (by calling rpc_ns_group_mbr_inq_next()), you will receive the corresponding global name.
2.4.7 – IDL Encoding Service Handle
An IDL encoding service handle is a pointer-size opaque variable
that points to functions that control how data encoding or decoding
is performed. The following routines return an IDL encoding service
handle and show an argument data type of idl_es_handle_t:
+ idl_es_encode_incremental()
+ idl_es_decode_buffer()
+ idl_es_decode_incremental()
+ idl_es_encode_dyn_buffer()
+ idl_es_encode_fixed_buffer()
The idl_es_handle_free() and idl_es_inq_encoding_id() routines
require an IDL encoding service handle.
Note that in order to use the IDL encoding services, you must
include a header file that has been generated for an application
that has used the encode and decode ACF attributes on one or more
of its operations.
2.4.8 – 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 DCE 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 DCE 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
+ The if-name variable is the interface identifier specified
in the IDL file.
+ The major-version variable is the interface's major-version
number specified in the IDL file.
+ The minor-version variable 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()
2.4.9 – Interface Identifier
The interface identifier (id) data structure contains the interface
UUID and major-version 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. The following routines require an
interface identifier:
+ 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()
2.4.10 – Interface Identifier Vector
The interface identifier (id) vector data structure contains a list
of interfaces offered by a server. The interface identifier vector
contains a count member (count), followed by an array of pointers to
interface identifiers (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 identifier vector is a read-only vector. To obtain a
vector of the interface identifiers 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 identifiers exported by a server
to a name service database, an application calls the
rpc_ns_mgmt_entry_inq_if_ids() routine.
The RPC runtime allocates memory for the interface identifier
vector. The application calls the rpc_if_id_vector_free() routine
to free the interface identifier vector.
2.4.11 – Manager Entry Point Vector
The manager Entry Point Vector (EPV) is an array of pointers to
remote procedures.
The DCE 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
+ The if-name variable is the interface identifier specified
in the IDL file.
+ The major-version variable is the interface's major-version
number specified in the IDL file.
+ The minor-version variable is the interface's minor-version
number specified in the IDL file.
By default, the DCE IDL compiler automatically creates and
initializes a manager EPV. DCE 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 DCE 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 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.
2.4.12 – 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:
+ 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.
2.4.13 – 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.
Valid Protocol Sequences
___________________________________________________________
Protocol Sequence Description
___________________________________________________________
ncacn_ip_tcp NCA Connection over Internet Protocol:
Transmission Control Protocol
ip or ncadg_ip_udp NCA Datagram over Internet Protocol:
User Datagram Protocol
ncacn_dnet_nsp NCA Connection over DECnet Phase IV
ncacn_osi_dna NCA Connection over DECnet/OSI
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.
2.4.14 – 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.
2.4.15 – 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_in
The number of remote procedure calls received by the
runtime.
rpc_c_stats_calls_out
The number of remote procedure calls initiated by the
runtime.
rpc_c_stats_pkts_in
The number of network packets received by the runtime.
rpc_c_stats_pkts_out
The 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.
2.4.16 – 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 authenti-
cation information sometimes associated with a binding handle into
the resulting string binding.
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 rpc_ep_register(),
rpc_ep_register_no_replace(), and rpc_ns_binding_export() routines.
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-uuid
This 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-sequence
This 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 the table in the entry on Protocol_Sequence.
This field is required.
: This symbol is the delimiter character for the RPC
protocol sequence field.
nw-addr This 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 hostname.
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 hostname 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 hostname 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 hostname.
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.
endpoint This 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 information on 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.
option This 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]
2.4.16.1 – 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 dashes 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 letters. The RPC
runtime routines that return a string UUID always return the
hexadecimal characters in lowercase letters.
The following routines require a string UUID:
+ rpc_string_binding_compose()
+ uuid_from_string()
The following routines return a string UUID:
+ rpc_string_binding_parse()
+ uuid_to_string()
2.4.16.2 – Unsigned Character String
DCE RPC treats all characters in strings as unsigned characters. Those routines with character string arguments show a data type of unsigned_char_t *.
2.4.16.3 – 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:
+ rpc_ep_register()
+ rpc_ep_register_no_replace()
+ rpc_ep_unregister()
+ rpc_ns_binding_export()
+ rpc_ns_binding_unexport()
+ rpc_ns_mgmt_binding_unexport()
2.5 – 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 that write permission does not imply read permission.
To find the ACL permissions for the NSI routines whose names begin
with rpc_ns, see these routines' reference pages.
The non-NSI routines whose names do not begin with rpc_ns do not
need ACL permissions, so their reference pages do not specify any.
2.6 – Frequently Used Routine Parameters
A few parameters are common to many of the DCE RPC routines. These parameters are described fully here and again briefly on the specific routine reference pages.
2.6.1 – binding
Used as an input or output parameter.
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 communications between the client and server. The
communications occur when a client makes a remote procedure call.
As an input parameter 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()
2.6.2 – name
Used as an input/output parameter. When used as an input parameter, the value of this parameter depends on the syntax selected in the name_syntax parameter. 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. Specifying NULL also has the called routine use the name syntax that the environment variable RPC_DEFAULT_ENTRY_SYNTAX specifies. For a name_syntax value of rpc_c_ns_syntax_dce, use the DCE naming rules to specify parameter name. As an output parameter, 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 parameter depends on the syntax selected in name_syntax. For a name_syntax value of rpc_c_ns_syntax_dce, name is returned using the DCE naming syntax. The DCE 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 parameter. The one exception is routine rpc_ns_entry_expand_name(); it always returns a name string.
2.6.3 – name_syntax
Used as an input parameter, 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 DCE RPC for entries in the name service
database.
Valid Name Syntaxes
________________________________________________
Constant Value Description
________________________________________________
rpc_c_ns_syntax_default 0 Default syntax
rpc_c_ns_syntax_dce 3 DCE
The name_syntax parameter tells routines how to parse the entry
name specified in an input name parameter or specifies the syntax
to use when returning an entry name as an output name parameter.
If the RPC_DEFAULT_ENTRY_SYNTAX environment variable is not
defined, the RPC runtime uses the rpc_c_ns_syntax_dce name syntax.
2.6.4 – string
Used as an input or output parameter. Returns a character string, which always includes the terminating null character \0. The DCE 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 parameter.
2.6.5 – status
Each routine in the RPC API returns a DCE 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 DCE status code to a text message, call the routine dce_error_inq_text(). Note that 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. For more information about the RPC status codes, see the OSF DCE Problem Determination Guide.
2.6.6 – uuid
Used as an input or output parameter. When you need to specify a nil UUID to a uuid input parameter in any of the DCE RPC routines, you can supply the value NULL.
2.7 – RELATED_INFORMATION
Books: OSF DCE Application Development Guide-Introduction & Style
Guide
OSF DCE Application Development Guide-Core Components
OSF DCE Application Development Guide-Directory Services
OSF DCE Command Reference
3 – Application Routines
These are the RPC application development routines.
3.1 – cs_byte_from_netcs
NAME
cs_byte_from_netcs - Converts international character data from a
network code set to a local code set
Used by client and server applications.
SYNOPSIS
#include <dce/codesets_stub.h>
void cs_byte_from_netcs( rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
idl_byte *network_data,
unsigned32 network_data_length,
unsigned32 local_buffer_size,
idl_byte *local_data,
unsigned32 *local_data_length,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain code set
conversion information. When called from the client stub, this
value is the binding handle of a compatible server returned by
the rpc_ns_binding_import_next() or rpc_ns_binding_select()
routine. When called from the server stub, this value is a
pointer to binding information that the client stub passed in
the RPC call.
network_code_set_value
The registered hexadecimal integer value that represents the code
set that was used to transmit character data over the network.
In general, the network'' code set is the code set that the client
application's code sets evaluation routine has determined to be
compatible for this client and server. When the caller is the
client stub, this value is the receiving tag. When the caller is
the server stub, this value is the sending tag.
network_data
A pointer to the international character data that has been
received, in the network code set encoding.
network_data_length
The number of idl_byte data elements to be converted. For a
varying array or a conformant varying array, this value is the
local value of the length_is variable. For a conformant array,
this value is the local value of the size_is variable. For a
fixed array, the value is the array size specified in the
interface definition.
local_buffer_size
A pointer to the buffer size to be allocated to contain the
converted data, in units of byte. The value specified in this
parameter is the local buffer size returned from the
cs_byte_local_size() routine.
Output
local_data
A pointer to the converted data, in idl_byte format.
local_data_length
The length of the converted data, in units of idl_byte. Specify
NULL if a fixed array is to be converted.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The specified code set does not match the code set
specified in the sending tag in the binding handle.
If this error occurs in the server stub, an
exception is raised to the client application.
When running the host converter, the following errors can occur:
rpc_s_ss_invalid_char_input
rpc_s_ss_short_conv_buffer
rpc_s_ss_iconv_error (HP-UX reference platform only)
rpc_s_ss_no_memory (HP-UX reference platform only)
When invoked from the server stub, the routine calls the
dce_cs_loc_to_rgy() routine and the host converter routines. If
these routines return an error, an exception is raised to the
client application.
DESCRIPTION
The cs_byte_from_netcs() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and code
sets environment.
The cs_byte_from_netcs() routine is one of the DCE RPC stub code set
conversion routines that RPC stubs use before they marshall or
unmarshall data to convert international character data to and from
local and network code sets.
Client and server stubs call the cs_byte_*_netcs() routines when
the cs_byte type has been specified as the local data type using
the cs_char attribute in the attribute configuration file for the
application. (the cs_byte type is equivalent to the byte type.)
Client and server stubs call the cs_byte_from_netcs() routine before
they unmarshall the international character data received from the
network. The routine takes a binding handle, a code set value that
identifies the code set used to transfer international character
data over the network, the address of the network data, in idl_byte
format, that may need to be converted, and the data length, in units
of idl_byte.
The routine compares the sending code set to the local code set
currently in use. If the routine finds that code set conversion is
necessary, (because the local code set differs from the code set
specified to be used on the network), it determines which host code
set converter to call to convert the data and then invokes that
converter.
The routine then returns the converted data, in idl_byte format. If
the data is a varying, conformant, or conformant varying array, the
routine also returns the length of the converted data, in units of
idl_byte.
Applications can specify local data types other than cs_byte and
wchar_t (the local data types for which DCE RPC supplies stub code
set conversion routines) with the cs_char ACF attribute. In this
case, the application must also supply local_type_to_netcs() and
local_type_from_netcs() stub conversion routines for this type.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: wchar_t_from_netcs
cs_byte_to_netcs
wchar_t_to_netcs
3.2 – cs_byte_local_size
NAME
cs_byte_local_size - Calculates the necessary buffer size for code
set conversion from a network code set to a
local code set
Used by client and server applications.
SYNOPSIS
#include <dce/codesets_stub.h>
void cs_byte_local_size( rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
unsigned32 network_buffer_size,
idl_cs_convert_t *conversion_type,
unsigned32 *local_buffer_size,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain buffer
size evaluation information. When called from the client stub,
this value is the binding handle of a compatible server returned
by the rpc_ns_binding_import_next() or rpc_ns_binding_select()
routine. When called from the server stub, this value is a
pointer to binding information that the client stub passed in
the RPC call.
network_code_set_value
The registered hexadecimal integer value that represents the
code set used to transmit character data over the network. In
general, the "network" code set is the code set that the client
application's code sets evaluation routine has determined to be
compatible for this client and server. When the caller is the
client stub, this value is the receiving tag. When the caller is
the server stub, this value is the sending tag.
network_buffer_size
The size, in units of idl_byte, of the buffer that is allocated
for the international character data. For a conformant or
conformant varying array, this value is the network value of the
size_is variable for the array; that is, the value is the size
of the unmarshalled string if no conversion is done.
Output
conversion_type
A pointer to the enumerated type defined in dce/idlbase.h that
indicates whether data conversion is necessary and whether or
not the existing buffer is sufficient for storing the results
of the conversion. The conversion type can be one of the
following values:
idl_cs_no_convert
No code set conversion is required.
idl_cs_in_place_convert
Code set conversion can be performed in the
current buffer.
idl_cs_new_buffer_convert
The converted data must be written to a new buffer.
local_buffer_size
A pointer to the buffer size that needs to be allocated to
contain the converted data, in units of idl_byte. This value
is to be used as the local value of the size_is variable for
the array, and is non-NULL only if a conformant or conformant
varying array is to be unmarshalled. A value of NULL in this
parameter indicates that a fixed or varying array is to be
unmarshalled.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The specified code set does not match the code set
specified in the sending tag in the binding handle.
If this error occurs in the server stub, an
exception is raised to the client application.
When invoked from the server stub, this routine calls the routines
dce_cs_loc_to_rgy() and rpc_rgy_get_max_bytes(). If either of these
routines returns an error, the cs_byte_local_size() routine raises
an exception to the client application.
DESCRIPTION
The cs_byte_local_size() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The cs_byte_local_size() routine is one of the DCE RPC buffer sizing
routines that RPC stubs use before they marshall or unmarshall data
to determine whether or not the buffers allocated for code set
conversion need to be enlarged to hold the converted data. The buffer
sizing routines determine the type of conversion required and
calculate the size of the necessary buffer (if a new one is required);
the RPC stub then allocates a buffer of that size before it calls one
of the code set conversion routines.
Client and server stubs call the cs_byte_*_size routines when the
cs_byte type has been specified as the local data type using the
cs_char attribute in the attribute configuration file for the
application.
Applications do not call cs_byte_local_size() routine directly.
Client and server stubs call the routine before they unmarshall any
data. The stubs pass the routine a binding handle and a code set
value that identifies the code set that was used to transfer
international character data over the network. The stubs also
specify the network storage size of the data, in units of idl_byte,
if a conformant or conformant varying array is to be unmarshalled,
or they specify NULL if a fixed or varying array is to be marshalled.
When called from a client stub, the cs_byte_local_size() routine
determines the value of conversion_type from the client and server's
code set tag information stored in the binding handle by a code sets
evaluation routine or a tag-setting routine. If the conversion type
specified in the handle is idl_cs_new_buffer_convert, the routine sets
the conversion_type parameter to this value and, if a conformant or
conformant varying array is to be unmarshalled, calculates a new
buffer size by multiplying the value of local_buffer_size by the
c_max_bytes value for the code set specified in
network_code_set_value. The routine returns the new buffer size in the
local_buffer_size parameter. The size is specified in units of
cs_byte, which is the local representation used for international
character data (and is equivalent to the byte data type). For fixed
and varying arrays, the routine assumes that network_buffer_size is
sufficient to store the converted data.
If the handle information specifies idl_cs_convert_in_place or
idl_cs_no_convert, the routine assumes that network_buffer_size can
store the converted data (or that no conversion is necessary) and
returns idl_cs_convert_in_place (or idl_cs_no_convert) in the
conversion_type parameter. The routine also returns the value of
network_buffer_size in local_buffer_size if a conformant or
conformant varying array is to be marshalled.
In cases where the binding handle does not contain the results of
character and code sets evaluation, or where it is being called from
the server stub, the cs_byte_local_size() routine determines the
value of conversion_type itself using the local code set value and
the code set value passed in the network_code_set_value parameter and
returns the appropriate conversion_type value. If a conformant or
conformant varying array is to be unmarshalled, and the routine finds
that a new buffer is required to hold the converted data, the routine
calculates the size of this new buffer (by multiplying the value of
network_buffer_size by the local code set c_max_bytes value) and
returns the results, in units of cs_byte, in local_buffer_size.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: cs_byte_net_size
wchar_t_local_size
wchar_t_net_size
3.3 – cs_byte_net_size
NAME
cs_byte_net_size - Calculates the necessary buffer size for code
set conversion from a local code set to a
network code set
Used by client and server applications.
SYNOPSIS
#include <dce/codesets_stub.h>
void cs_byte_net_size( rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
unsigned32 local_buffer_size,
idl_cs_convert_t *conversion_type,
unsigned32 *network_buffer_size,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain buffer
size evaluation information. When called from the client stub,
this value is the binding handle of a compatible server returned
by the rpc_ns_binding_import_next() or rpc_ns_binding_select()
routine. When called from the server stub, this value is a
pointer to binding information that the client stub passed in
the RPC call.
network_code_set_value
The registered hexadecimal integer value that represents
the code set to be used to transmit character data over the
network. In general, the "network" code set is the code set
that the client application's code sets evaluation routine has
determined to be compatible for this client and server. When
the caller is the client stub, this value is the sending tag.
When the caller is the server stub, this value is the receiving
tag.
local_buffer_size
The size, in units of idl_byte, of the buffer that is allocated
for the international character data. This value is the local
value of the size_is variable for the array; that is, the value
is the size of the marshalled string if no conversion is done.
Output
conversion_type
A pointer to the enumerated type defined in dce/idlbase.h that
indicates whether data conversion is necessary and whether or
not existing storage is sufficient for storing the results of
the conversion. The conversion type can be one of the following
values:
idl_cs_no_convert
No code set conversion is required.
idl_cs_in_place_convert
Code set conversion can be performed in the
current buffer.
idl_cs_new_buffer_convert
The converted data must be written to a new buffer.
network_buffer_size
A pointer to the buffer size that needs to be allocated to contain
the converted data, in units of idl_byte. This value is to be used
as the network value of the size_is variable for the array, and is
non-NULL only if a conformant or conformant varying array is to be
marshalled. A value of NULL in this parameter indicates that a
fixed or varying array is to be marshalled.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The specified code set does not match the code
set specified in the sending tag in the binding
handle. If this error occurs in the server
stub, an exception is raised to the client
application.
When invoked from the server stub, this routine calls the routines
dcs_cs_loc_to_rgy() and rpc_rgy_get_max_bytes(). If either of
these routines returns an error, the cs_byte_net_size() routine
raises an exception to the client application.
DESCRIPTION
The cs_byte_net_size() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The cs_byte_net_size() routine is one of the DCE RPC buffer sizing
routines that RPC stubs use before they marshall or unmarshall data
to determine whether or not the buffers allocated for code set
conversion need to be enlarged to hold the converted data. The
buffer sizing routines determine the type of conversion required
and calculate the size of the necessary buffer (if a new one is
required). The RPC stub then allocates a buffer of that size before
it calls one of the code set conversion routines.
Client and server stubs call the cs_byte_*_size routines when the
cs_byte type (which is equivalent to byte) has been specified as
the local data type using the cs_char attribute in the attribute
configuration file for the application. Applications do not call
the cs_byte_net_size() routine directly. Client and server stubs
call the routine before they marshall any data. The stubs pass the
routine a binding handle and a code set value that identifies the
code set to be used to transfer international character data over
the network. The stubs also specify the local storage size of the
data, in units of byte.
When called from a client stub, the cs_byte_net_size() routine
determines the value of conversion_type from the client and server's
code set tag information set up the binding handle by a code sets
evaluation routine or a tag-setting routine. If the conversion type
specified in the handle is idl_cs_new_buffer_convert, the routine
sets the conversion_type parameter to this value and, if a
conformant or conformant varying array is to be marshalled,
calculates a new buffer size by multiplying the value of
local_buffer_size by the c_max_bytes value for the code set
specified in network_code_set_value (the sending tag parameter).
The routine returns the new buffer size in the network_buffer_size
parameter. The size is specified in units of cs_byte, which is the
network representation used for international character data (and
is equivalent to the byte type). For fixed and varying arrays, the
routine assumes that local_buffer_size is sufficient to store the
converted data.
If the handle information specifies idl_cs_convert_in_place or
idl_cs_no_convert, the routine assumes that local_buffer_size can
store the converted data (or that no conversion is necessary) and
returns idl_cs_convert_in_place (or idl_cs_no_convert) in the
conversion_type parameter. The routine also returns the value of
local_buffer_size in network_buffer_size if a conformant or
conformant varying array is to be marshalled.
In cases where the binding handle does not contain the results of
character and code sets evaluation, or where it is being called from
the server stub, the cs_byte_net_size() routine determines the value
of conversion_type itself using the local code set value and the
code set value passed in the network_code_set_value parameter and
returns the appropriate conversion_type value. If a conformant or
conformant varying array is to be marshalled, and the routine finds
that a new buffer is required to hold the converted data, the routine
calculates the size of this new buffer (by multiplying the value of
local_buffer_size by the network code set c_max_bytes value) and
returns the results, in units of cs_byte, in network_buffer_size.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: cs_byte_local_size
wchar_t_local_size
wchar_t_net_size
3.4 – cs_byte_to_netcs
NAME
cs_byte_to_netcs - Converts international character data from a
local code set to a network code set
Used by client and server applications.
SYNOPSIS
#include <dce/codesets_stub.h>
void cs_byte_to_netcs( rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
idl_byte *local_data,
unsigned32 local_data_length,
idl_byte *network_data,
unsigned32 *network_data_length,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain code
set conversion information. When called from the client stub,
this value is the binding handle of a compatible server returned
by the rpc_ns_binding_import_next() or rpc_ns_binding_select()
routine. When called from the server stub, this value is a
pointer to binding information that the client stub passed in
the RPC call.
network_code_set_value
The registered hexadecimal integer value that represents the
code set to be used to transmit character data over the network.
In general, the network'' code set is the code set that the
client application's code sets evaluation routine has determined
to be compatible for this client and server. When the caller is
the client stub, this value is the sending tag. When the caller
is the server stub, this value is the receiving tag.
local_data
A pointer to the international character data to be transmitted,
in the local code set encoding.
local_data_length
The number of idl_byte data elements to be converted. For a
varying array or a conformant varying array, this value is the
local value of the length_is variable. For a conformant array,
this value is the local value of the size_is variable. For a
fixed array, the value is the array size specified in the
interface definition.
Output
network_data
A pointer to the converted data, in units of idl_byte.
network_data_length
A pointer to the length of the converted data, in units of
idl_byte. Specify NULL if a fixed or conformant array is to
be converted.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The specified code set does not match the code set
specified in the sending tag in the binding handle.
If this error occurs in the server stub, an
exception is raised to the client application.
When running the host converter, the following errors can occur:
rpc_s_ss_invalid_char_input
rpc_s_ss_short_conv_buffer
rpc_s_ss_iconv_error (HP-UX reference platform only)
rpc_s_ss_no_memory (HP-UX reference platform only)
When invoked from the server stub, the routine calls the
dce_cs_loc_to_rgy() routine and the host converter routines. If
these routines return an error, an exception is raised to the
client application.
DESCRIPTION
The cs_byte_to_netcs() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The cs_byte_to_netcs() routine is one of the DCE RPC stub code set
conversion routines that RPC stubs use before they marshall or
unmarshall data to convert international character data to and from
local and network code sets.
Client and server stubs call the cs_byte_*_netcs() routines when
the cs_byte type has been specified as the local data type using
the cs_char attribute in the attribute configuration file for the
application. (The cs_byte type is equivalent to the byte type.)
Client and server stubs call the cs_byte_to_netcs() routine before
they marshall any data. The routine takes a binding handle, a code
set value that identifies the code set to be used to transfer
international character data over the network, the address of the
data to be converted, and the length of the data to be converted,
in units of idl_byte.
The routine compares the code set specified as the network code set
to the local code set currently in use. If the routine finds that
code set conversion is necessary, (because the local code set differs
from the code set specified to be used on the network), it determines
which host code set converter to call to convert the data and then
invokes that converter.
The routine then returns the converted data, in idl_byte format.
If the data is a varying, conformant, or conformant varying array,
the routine also returns the length of the converted data, in units
of idl_byte.
Applications can specify local data types other than cs_byte and
wchar_t (the local data types for which DCE RPC supplies stub code
set conversion routines) with the cs_char ACF attribute. In this
case, the application must also supply local_type_to_netcs() and
local_type_from_netcs() stub conversion routines for this type.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: cs_byte_from_netcs
wchar_t_from_netcs
wchar_t_to_netcs
3.5 – dce_cs_loc_to_rgy
NAME
dce_cs_loc_to_rgy - Maps a local name for a code set to a code set
value in the code set registry
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>
void dce_cs_loc_to_rgy( idl_char *local_code_set_name,
unsigned32 *rgy_code_set_value,
unsigned16 *rgy_char_sets_number,
unsigned16 **rgy_char_sets_value,
error_status_t *status );
PARAMETERS
Input
local_code_set_name
A string that specifies the name that the local host's locale
environment uses to refer to the code set. The string is a
maximum of 32 bytes: 31 character data bytes plus a terminating
NULL character.
Output
rgy_code_set_value
The registered integer value that uniquely identifies the code
set specified by local_code_set_name.
rgy_char_sets_number
The number of character sets that the specified code set encodes.
Specifying NULL prevents this routine from returning this
parameter.
rgy_char_sets_value
A pointer to an array of registered integer values that uniquely
identify the character set(s) that the specified code set
encodes. Specifying NULL prevents this routine from returning
this parameter. The routine dynamically allocates this value.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
dce_cs_c_ok
dce_cs_c_cannot_allocate_memory
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
dce_cs_c_unknown
dce_cs_c_not_found
DESCRIPTION
The dce_cs_loc_to_rgy() routine is a DCE function that maps
operating system-specific names for character/code set encodings
to their unique identifiers in the code set registry.
The routine is currently used by the DCE RPC routines for character
and code set interoperability, which permit DCE RPC clients and
servers to transfer international character data in a heterogeneous
character set and code sets environment.
The dce_cs_loc_to_rgy() routine takes as input a string that holds
the host-specific local name'' of a code set and returns the
corresponding integer value that uniquely identifies that code set,
as registered in the host's code set registry. If the integer value
does not exist in the registry, the routine returns the status
dce_cs_c_unknown. The routine also returns the number of character
sets that the code set encodes and the registered integer values that
uniquely identify those character sets. Specifying NULL in the
rgy_char_sets_number and rgy_char_sets_value[] parameters prevents
the routine from performing the additional search for these values.
Applications that want only to obtain a code set value from the code
set registry can specify NULL for these parameters in order to
improve the routine's performance. If the value is returned from the
routine, application developers should free the array after it is
used, since the array is dynamically allocated.
The DCE RPC code sets compatibility evaluation routines
rpc_cs_eval_with_universal(), rpc_cs_eval_without_universal(), and
rpc_cs_character_set_compat_check() use this routine to obtain
registered integer values for a client and server's supported
character sets in order to ensure that the server supports a
character set that is compatible with the client. The DCE RPC stub
support routines for code set conversion can use this routine to
obtain the registered code set value that corresponds to the code
set they are currently using; that is, the local code set specified
in their host's locale environment. The stub routines for code set
conversion then compare their local code set value to the code set
value specified in the sending tag for the call to determine whether
code set conversion is necessary.
In general, programmers who are developing RPC applications that
transfer international characters do not need to call this routine
directly; the DCE RPC routines provided for code sets evaluation and
the DCE RPC stub support routines for code set conversion call this
routine on the client or server application's behalf.
However, programmers who are developing their own stub support
routines for code set conversion may want to include this routine in
their conversion code to map their current locale information to a
code set value in order to perform local-to-sending tag code set
comparison.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Commands: csrc
Functions: dce_cs_rgy_to_loc
rpc_cs_char_set_compat_check
rpc_cs_eval_with_universal
rpc_cs_eval_without_universal
rpc_rgy_get_code_sets
3.6 – dce_cs_rgy_to_loc
NAME
dce_cs_rgy_to_loc - Maps a code set value in the code set registry
to the local name for a code set
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>
void dce_cs_rgy_to_loc( unsigned32 *rgy_code_set_value,
idl_char **local_code_set_name,
unsigned16 *rgy_char_sets_number,
unsigned16 **rgy_char_sets_value,
error_status_t *status );
PARAMETERS
Input
rgy_code_set_value
The registered hexadecimal value that uniquely identifies the
code set.
Output
local_code_set_name
A string that specifies the name that the local host's locale
environment uses to refer to the code set. The string is a
maximum of 32 bytes: 31 character data bytes and a terminating
NULL character.
rgy_char_sets_number
The number of character sets that the specified code set encodes.
Specifying NULL in this parameter prevents the routine from
returning this value.
rgy_char_sets_value
A pointer to an array of registered integer values that uniquely
identify the character set(s) that the specified code set
encodes. Specifying NULL in this parameter prevents the routine
from returning this value. The routine dynamically allocates this
value.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
dce_cs_c_ok
dce_cs_c_cannot_allocate_memory
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
dce_cs_c_unknown
dce_cs_c_not_found
DESCRIPTION
The dce_cs_rgy_to_loc() routine is a DCE function that maps a unique
identifier for a code set in the code set registry to the operating
system-specific name for the code set, if it exists in the code set
registry.
The routine is currently used by the DCE RPC routines for character
and code set interoperability, which permit DCE applications to
transfer international characters in a heterogeneous character and
code sets environment.
The dce_cs_rgy_to_loc() routine takes as input a registered integer
value of a code set and returns a string that holds the operating
system-specific, or local name, of the code set.
If the local code set name does not exist in the registry, the
routine returns the status dce_cs_c_unknown and returns an
undefined string.
The routine also returns the number of character sets that the code
set encodes and the registered integer values that uniquely identify
those character sets. Specifying NULL in the rgy_char_sets_number
and rgy_char_sets_value[] parameters prevents the routine from
performing the additional search for these values. Applications
that want only to obtain a local code set name from the code set
registry can specify NULL for these parameters in order to improve
the routine's performance. If the value is returned from the
routine, application developers should free the rgy_char_sets_value
array after it is used.
In general, client and server applications that use the DCE RPC
character and code set interoperablity features do not need to call
this routine directly; the DCE RPC stub support routines provided
for code set conversion call this routine on the client or server
application's behalf to obtain the string name that matches the
name of the host code set converter that they will call to perform
the actual code set conversion.
However, application programmers who are developing their own RPC
stub support routines for code set conversion may want to include
this routine in their conversion code to map code set values sent
in code set tags into the local names for the code sets so that they
can locate the correct operating system code set converter.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Commands: csrc.
Functions: dce_cs_loc_to_rgy
rpc_cs_char_set_compat_check
rpc_cs_eval_with_universal
rpc_cs_eval_without_universal
rpc_rgy_get_code_sets
3.7 – idl_es_decode_buffer
NAME
idl_es_decode_buffer - Returns a buffer decoding handle to the IDL
encoding services
SYNOPSIS
void idl_es_decode_buffer( idl_byte *encoded_data_buffer,
idl_ulong_int buffer_size,
idl_es_handle_t *es_handle,
error_status_t *status );
PARAMETERS
Input
encoded_data_buffer
The address of the buffer that contains the data to be decoded.
buffer_size
The number of bytes of data in the buffer to be decoded.
Output
es_handle
Returns the address of an IDL encoding services handle for use
by a client or server decoding operation.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
include:
rpc_s_ok Success.
rpc_s_ss_bad_buffer
Bad buffer operation.
rpc_s_no_memory
Insufficient memory available to complete
operation.
DESCRIPTION
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte stream
without invoking the RPC runtime. Encoding and decoding operations are
analogous to marshalling and unmarshalling, except that the data is
stored locally, and is not transmitted over the network. Client and
server applications can use the IDL encoding services to create
persistent storage for their data. Encoding "flattens" complex data
types into a byte stream for storage on disk, while decoding restores
the flattened data to complex form.
The idl_es_decode_buffer() routine belongs to a set of routines that
return handles to the IDL encoding services for use by client and
server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_decode_buffer() routine returns a buffer decoding handle,
which directs the IDL encoding services to decode data from a single
application-supplied buffer of encoded data.
RETURNED VALUES
None.
RELATED INFORMATION
Function: idl_es_decode_incremental
3.8 – idl_es_decode_incremental
NAME
idl_es_decode_incremental - Returns an incremental decoding handle
to the IDL encoding services
Used by client and server applications.
SYNOPSIS
void idl_es_decode_incremental( idl_void_p_t state,
idl_es_read_fn_t read_fn,
idl_es_handle_t *es_handle,
error_status_t *status );
PARAMETERS
Input/Output
state
Specifies the address of an application-provided data structure
that coordinates the actions of successive calls to the read_fn
routine. The state data structure acts as a communications
channel between the application and the read_fn routine.
Input
read_fn
Specifies the address of a user-provided routine that generates
a buffer of encoded data for decoding by the IDL encoding
services. The IDL encoding services call the read_fn routine
repeatedly until all of the data has been decoded.
The following C definition for idl_es_read_fn_t illustrates the
prototype for the read_fn routine:
typedef void (*idl_es_read_fn_t)
(
idl_void_p_t state, /* in/out */
idl_byte **buffer, /* in */
idl_ulong_int *size, /* in */
);
The idl_es_decode_incremental() routine passes the specified
state parameter value as input to the read_fn routine. The
state data structure is the communications path between the
application and the read_fn routine. For example, the
application can use the state parameter to pass in an open
file pointer from which the read_fn routine is to read encoded
data.
The buffer parameter specifies the address of the data to be
decoded; this address must be 8-byte aligned. The size parameter
specifies the size of the buffer to be decoded, and must be a
multiple of 8 bytes unless it represents the size of the last
buffer to be decoded. The read_fn routine should return an
exception on error.
Output
es_handle
Returns the address of an IDL encoding services handle for use
by a client or server decoding operation.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status code and its meaning is as
follows:
rpc_s_ok Success.
rpc_s_no_memory
Insufficient memory available to complete
operation.
DESCRIPTION
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte stream
without invoking the RPC runtime. Encoding and decoding operations are
analogous to marshalling and unmarshalling, except that the data is
stored locally, and is not transmitted over the network. Client and
server applications can use the IDL encoding services to create
persistent storage for their data. Encoding "flattens" complex data
types into a byte stream for storage on disk, while decoding restores
the flattened data to complex form.
The idl_es_decode_incremental() routine belongs to a set of routines
that return handles to the IDL encoding services for use by client
and server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_decode_incremental() routine returns an incremental
decoding handle, which directs the IDL encoding services to decode
data by calling the user-supplied read_fn routine, which generates
a small buffer of encoded data for the IDL encoding services to
decode. The routine passes the buffer address and size to the IDL
encoding services, which then decode the buffer. The IDL encoding
services call the read_fn routine repeatedly until there is no more
data to decode.
RETURN VALUES
None.
RELATED INFORMATION
Functions: idl_es_encode_incremental
idl_es_decode_buffer
3.9 – idl_es_encode_dyn_buffer
NAME
idl_es_encode_dyn_buffer - Returns a dynamic buffer encoding handle
to the IDL encoding services
Used by client and server applications.
SYNOPSIS
void idl_es_encode_dyn_buffer( idl_byte **encoded_data_buffer,
idl_ulong_int *buffer_size,
idl_es_handle_t *es_handle,
error_status_t *status );
PARAMETERS
Input
None.
Output
encoded_data_buffer
The address to which the IDL encoding services will write the
address of the buffer that contains the encoded data, when the
encoding process is complete. When the application no longer
needs the buffer, it should release the memory resource. See
the OSF DCE Application Development Guide-Core Components for
an explanation of how to manage memory when using the IDL
encoding services.
buffer_size
The address to which the IDL encoding services will write the
size of the buffer that contains the encoded data, when the
encoding process is complete.
es_handle
Returns the address of an IDL encoding services handle for use
by a client or server encoding operation.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_ss_bad_buffer
Bad buffer operation.
rpc_s_no_memory
Insufficient memory available to complete
operation.
DESCRIPTION
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte stream
without invoking the RPC runtime. Encoding and decoding operations are
analogous to marshalling and unmarshalling, except that the data is
stored locally, and is not transmitted over the network. Client and
server applications can use the IDL encoding services to create
persistent storage for their data. Encoding "flattens" complex data
types into a byte stream for storage on disk, while decoding restores
the flattened data to complex form.
The idl_es_encode_dyn_buffer() routine belongs to a set of routines
that return handles to the IDL encoding services for use by client
and server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_encode_dyn_buffer() routine returns a dynamic buffer
encoding handle, which directs the IDL encoding services to store
the encoded data in a chain of small buffers, build an additional
single buffer that contains the encoded data, and pass that buffer's
address to the application. Dynamic buffering is the most expensive
style of IDL encoding services buffering, since two copies of the
encoded data exist (one in the chain of buffers, and one in the
single buffer).
RETURN VALUES
None.
RELATED INFORMATION
Functions: idl_es_encode_fixed_buffer
idl_es_encode_incremental
3.10 – idl_es_encode_fixed_buffer
NAME
idl_es_encode_fixed_buffer - Returns a fixed buffer encoding handle
to the IDL encoding services
SYNOPSIS
void idl_es_encode_fixed_buffer( idl_byte *data_buffer,
idl_ulong_int data_buffer_size,
idl_ulong_int *encoded_buffer_size,
idl_es_handle_t *es_handle,
error_status_t *status );
PARAMETERS
Input
data_buffer
The address of the application-supplied buffer. This address
must be 8-byte aligned.
data_buffer_size
The size of the application-supplied buffer. The size must be
a multiple of 8 bytes.
Output
encoded_buffer_size
Returns the address to which the IDL encoding services write
the size of the encoded buffer when they have completed
encoding the data.
es_handle
Returns the address of an IDL encoding services handle for use
by a client or server encoding operation.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_bad_buffer
Bad buffer operation.
rpc_s_no_memory
Insufficient memory available to complete
operation.
DESCRIPTION
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a
byte stream and decoding data types in output parameters from a byte
stream without invoking the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except
that the data is stored locally, and is not transmitted over the
network. Client and server applications can use the IDL encoding
services to create persistent storage for their data. Encoding
"flattens" complex data types into a byte stream for storage on
disk, while decoding restores the flattened data to complex form.
The idl_es_encode_fixed_buffer() routine belongs to a set of routines
that return handles to the IDL encoding services for use by client
and server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_encode_fixed_buffer() routine returns a fixed buffer
encoding handle, which directs the IDL encoding services to encode
data into a single buffer that the application has provided. The
fixed buffer encoding style is useful for applications that need
only one buffer for their encoding and decoding process. The buffer
that the application allocates must be large enough to hold all of
the encoded data, and must also allocate 56 bytes for each encoding
operation that the application has defined (this space is used to
hold per-operation header information.)
RETURN VALUES
None.
RELATED INFORMATION
Functions: idl_es_encode_dyn_buffer
idl_es_encode_incremental
3.11 – idl_es_encode_incremental
NAME
idl_es_encode_incremental - Returns an incremental encoding handle
to the IDL encoding services
Used by client and server applications.
SYNOPSIS
void idl_es_encode_incremental( idl_void_p_t state,
idl_es_allocate_fn_t allocate_fn,
idl_es_write_fn_t write_fn,
idl_es_handle_t *es_handle,
error_status_t *status );
PARAMETERS
Input/Output
state
Specifies the address of an application-provided data structure
that coordinates the actions of the allocate_fn and write_fn
routines. The state data structure acts as a communications
channel between the application and the allocate_fn and
write_fn routines.
Input
allocate_fn
Specifies the address of a user-provided routine that allocates
an empty buffer. The encoding stub uses the allocated buffer to
store encoded data.
The following C definition for idl_es_allocate_fn_t illustrates
the prototype for the buffer allocation routine:
typedef void (*idl_es_allocate_fn_t)
(
idl_void_p_t state, /* in/out */
idl_byte **buffer, /* out */
idl_ulong_int *size, /* in/out */
);
The idl_es_encode_incremental() routine passes the specified
state parameter value as input to the allocate_fn buffer
allocation routine. When the IDL encoding services call the
allocate_fn routine, the value at the address indicated by
size represents the buffer size that the IDL encoding services
have requested the routine to allocate. When the allocate_fn
buffer allocation routine allocates the buffer, it writes the
actual size of the allocated buffer to this parameter; the value
must be a multiple of eight bytes. The buffer parameter
specifies the address of the allocated buffer; this address must
be 8-byte aligned. The allocate_fn routine should return an
exception on error.
write_fn
Specifies the address of a user-provided routine that writes the
contents of a buffer that contains data that has been encoded by
the IDL encoding services. The IDL encoding services will call
this routine when the buffer allocated by allocate_fn is full,
or when all of the application's encoding operation parameters
have been encoded.
The following C definition for idl_es_write_fn_t illustrates the
prototype for the write_fn routine:
typedef void (*idl_es_write_fn_t)
(
idl_void_p_t state, /* in/out */
idl_byte *buffer, /* in */
idl_ulong_int size, /* in */
);
The idl_es_encode_incremental() routine passes the specified
state parameter value as input to the write_fn routine. The
buffer parameter value is the address of the data that the
IDL encoding services have encoded. The size parameter value
is the size, in bytes, of the encoded data.
The write_fn routine should return an exception on error.
Output
es_handle
Returns the address of an IDL encoding services handle for use
by a client or server encoding operation.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_no_memory
Insufficient memory available to complete
operation.
DESCRIPTION
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte
stream without invoking the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except that
the data is stored locally, and is not transmitted over the network.
Client and server applications can use the IDL encoding services to
create persistent storage for their data. Encoding "flattens"
complex data types into a byte stream for storage on disk, while
decoding restores the flattened data to complex form.
The idl_es_encode_incremental() routine belongs to a set of routines
that return handles to the IDL encoding services for use by client
and server encoding and decoding operations. The information in the
handle controls the way in which the IDL encoding services manage
memory when encoding or decoding data.
The idl_es_encode_incremental() routine returns an incremental
encoding handle, which directs the IDL encoding services to encode
data into a chain of small buffers that the user-provided
allocate_fn routine manages. The user-provided write_fn routine
writes the encoded data in these buffers back for access by the
application.
The state data structure is the communications path between the
application and the allocate_fn and write_fn routines. For example,
the application can build a cache of pre-allocated memory to store
encoded data, and store pointers to that pre-allocated memory in the
state data structure. When invoked by the IDL encoding services to
allocate a buffer, the allocate_fn routine can search the state data
structure for a free memory location to use.
RETURN VALUES
None.
RELATED INFORMATION
Functions: idl_es_decode_incremental
idl_es_encode_fixed_buffer
idl_es_encode_dyn_buffer
3.12 – idl_es_handle_free
NAME
idl_es_handle_free - Frees an IDL encoding services handle
SYNOPSIS
void idl_es_handle_free( idl_es_handle_t *es_handle,
error_status_t *status );
PARAMETERS
Input/Output
es_handle
The address of the handle whose resources are to be freed.
The handle is made NULL by this operation.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status code and its meaning is
as follows:
rpc_s_ok Success.
DESCRIPTION
The idl_es_handle_free routine frees an IDL encoding services handle
that has been allocated by one of the IDL encoding services handle-
returning routines.
RETURNED VALUES
None.
RELATED INFORMATION
Functions: idl_es_decode_buffer
idl_es_decode_incremental
idl_es_encode_dyn_buffer
idl_es_encode_fixed_buffer
idl_es_encode_incremental
3.13 – idl_es_inq_encoding_id
NAME
idl_es_inq_encoding_id - Identifies an operation within an interface
that has been called to encode data using
the IDL encoding services
SYNOPSIS
void idl_es_inq_encoding_id( idl_es_handle_t es_handle,
rpc_if_id_t *if_id,
idl_ulong_int *op_num,
error_status_t *status );
PARAMETERS
Input
es_handle
A encoding services handle returned by one of the IDL encoding
services handle-returning routines.
Output
if_id
Returns the interface UUID and version number assigned to the
interface that defines the operation that encoded the data.
This information is stored in the IDL encoding services handle
that is associated with the encoded data.
op_num
Returns the operation number assigned to the operation that
encoded the data. Operations are numbered in the order in
which they appear in the interface definition, starting with
zero (0). The operation number for the operation that encoded
the data is stored in the IDL encoding services handle that
is associated with the encoded data.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_unknown_if
Interface identifier and operation number
unavailable.
DESCRIPTION
The IDL encoding services provide client and server RPC applications
with a method for encoding data types in input parameters into a byte
stream and decoding data types in output parameters from a byte
stream without invoking the RPC runtime. Encoding and decoding
operations are analogous to marshalling and unmarshalling, except
that the data is stored locally, and is not transmitted over the
network. Client and server applications can use the IDL encoding
services to create persistent storage for their data. Encoding
"flattens" complex data types into a byte stream for storage on
disk, while decoding restores the flattened data to complex form.
The idl_es_inq_encoding_id() routine returns the identity of an
operation within an application that has been invoked to encode data
using the IDL encoding services. Applications can use this routine
to determine the identity of an encoding operation, for example,
before calling their decoding operations.
RETURN VALUES
None.
RELATED INFORMATION
Functions: idl_es_decode_buffer
idl_es_decode_incremental
idl_es_encode_dyn_buffer
idl_es_encode_fixed_buffer
idl_es_encode_incremental
3.14 – rpc_binding_copy
NAME
rpc_binding_copy - Returns a copy of a binding handle
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_copy( rpc_binding_handle_t source_binding,
rpc_binding_handle_t *destination_binding,
unsigned32 *status );
PARAMETERS
Input
source_binding
Specifies the server binding handle whose referenced binding
information is copied.
Output
destination_binding
Returns the server binding handle that refers to the copied
binding information.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_binding_copy() routine copies the server binding information
referenced by the binding handle specified in the source_binding
parameter. This routine returns a new server binding handle for the
copied binding information. The new server binding handle is returned
in the destination_binding parameter.
Use the rpc_binding_copy() routine if you want a change (made to
binding information by one thread) not to affect the binding infor-
mation used by other threads. The explanation of binding handles in
the rpc_intro reference page has more detail about this use of
routine rpc_binding_copy().
After calling this routine, operations performed on the source_binding
binding handle do not affect the binding information referenced by the
destination_binding binding handle. Similarly, operations performed on
the destination_binding binding handle do not affect the binding
information referenced by the source_binding binding handle.
If you want the changes made to binding information by one thread to
affect the binding information used by other threads, your program
must share a single binding handle across the threads. In this case
the application controls binding handle concurrency.
When an application is finished using the binding handle specified
by the destination_binding parameter, the application calls the
rpc_binding_free() routine to release the memory used by the
destination_binding binding handle and its referenced binding
information.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_free
3.15 – rpc_binding_free
NAME
rpc_binding_free - Releases binding handle resources
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_free( rpc_binding_handle_t *binding,
unsigned32 *status );
PARAMETERS
Input/Output
binding
Specifies the server binding handle to free.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_binding_free() routine frees the memory used by a server
binding handle and its referenced binding information. Use this
routine when your application is finished using a server binding
handle that was dynamically created during program execution.
If the free-binding operation succeeds, the binding parameter returns
the value NULL.
An application can dynamically create binding handles by calling any
of the following routines:
+ rpc_binding_copy()
+ rpc_binding_from_string_binding()
+ rpc_ns_binding_import_next()
+ rpc_ns_binding_select()
+ rpc_server_inq_bindings()
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_copy
rpc_binding_from_string_binding
rpc_binding_vector_free
rpc_ns_binding_import_next
rpc_ns_binding_lookup_next
rpc_ns_binding_select
rpc_server_inq_bindings
3.16 – rpc_binding_from_string_binding
NAME
rpc_binding_from_string_binding - Returns a binding handle from a
string representation
Used by client or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_from_string_binding( unsigned_char_t *string_binding,
rpc_binding_handle_t *binding,
unsigned32 *status );
PARAMETERS
Input
string_binding
Specifies a string representation of a binding handle.
Output
binding
Returns the server binding handle.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_arg
Invalid argument.
rpc_s_invalid_endpoint_format
Invalid endpoint format.
rpc_s_invalid_rpc_protseq
Invalid protocol sequence.
rpc_s_invalid_string_binding
Invalid string binding.
rpc_s_protseq_not_supported
Protocol sequence not supported on this host.
uuid_s_bad_version
Bad UUID version.
uuid_s_invalid_string_uuid
Invalid format for a string UUID.
DESCRIPTION
The rpc_binding_from_string_binding() routine creates a server binding
handle from a string representation of a binding handle.
The string_binding parameter does not need to contain an object UUID.
In this case, the returned binding contains a nil UUID.
If the provided string_binding parameter does not contain an endpoint
field, the returned binding parameter is a partially bound server
binding handle.
If the provided string_binding parameter does contain an endpoint
field, the returned binding parameter is a fully bound server binding
handle with a well-known endpoint.
If the provided string_binding parameter does not contain a host
address field, the returned binding parameter refers to the local
host.
To create a string binding, call the rpc_string_binding_compose()
routine or call the rpc_binding_to_string_binding() routine or
provide a character string constant.
When an application finishes using the binding parameter, the
application calls the rpc_binding_free() routine to release the
memory used by the binding handle.
The rpc_intro reference page contains an explanation of partially
and fully bound binding handles.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_copy
rpc_binding_free
rpc_binding_to_string_binding
rpc_string_binding_compose
3.17 – rpc_binding_inq_auth_client
NAME
rpc_binding_inq_auth_client - Returns authentication and authorization
information from the binding handle for
an authenticated client. This call is
provided only for compatibility with
pre-1.1 DCE applications. DCE Release
1.1 and later applications should use
the rpc_binding_inq_auth_caller() call.
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
#include <dce/id_base.h>
void rpc_binding_inq_auth_client( rpc_binding_handle_t binding,
rpc_authz_handle_t *privs,
unsigned_char_t **server_princ_name,
unsigned32 *protect_level,
unsigned32 *authn_svc,
unsigned32 *authz_svc,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies the client binding handle from which to return the
authentication and authorization information.
Output
privs
Returns a handle to the authorization information for the client
that made the remote procedure call on binding.
The server must cast this handle to the data type specified by
authz_svc. The following table shows how to cast the return
value.
Casts for Authorization Information
____________________________________________________________________
For authz_svc value: privs contains this data: Use this cast:
____________________________________________________________________
rpc_c_authz_none A NULL value. None
rpc_c_authz_name The calling client's (unsigned_char_t *)
principal name.
rpc_c_authz_dce The calling client's (sec_id_pac_t *)
privilege attribute
certificate.
Note that rpc_c_authz_none is valid only if the authn_svc
parameter is rpc_c_authn_none.
The data referenced by this parameter is read-only and should not
be modified by the server. If the server wants to preserve any
of the returned data, it must copy the data into server-allocated
memory. Specifying NULL prevents the routine from returning this
parameter.
server_princ_name
Returns a pointer to the server principal name specified by the
client that made the remote procedure call on binding. The
content of the returned name and its syntax is defined by the
authentication service in use.
Specifying NULL prevents the routine from returning this
parameter. In this case, the caller does not have to call the
rpc_string_free() routine.
protect_level
Returns the protection level requested by the client that made the
remote procedure call on binding. The protection level determines
the degree to which authenticated communications between the
client and the server are protected. Specifying NULL prevents the
routine from returning this parameter. The possible protection
levels are as follows:
rpc_c_protect_level_default
Uses the default protection level for the specified
authentication service.
rpc_c_protect_level_none
Performs no protection.
rpc_c_protect_level_connect
Performs protection only when the client establishes
a relationship with the server.
rpc_c_protect_level_call
Performs protection only at the beginning of each
remote procedure call when the server receives the
request.
rpc_c_protect_level_pkt
Ensures that all data received is from the expected
client.
rpc_c_protect_level_pkt_integ
Ensures and verifies that none of the data
transferred between client and server has been
modified.
rpc_c_protect_level_pkt_privacy
Performs protection as specified by all of the
previous levels and also encrypt each remote
procedure call argument value.
authn_svc
Returns the authentication service requested by the client that
made the remote procedure call on binding.
Specifying NULL prevents the routine from returning this
parameter.
The possible authentication services are as follows:
rpc_c_authn_none
No authentication.
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
rpc_c_authn_default
DCE default authentication service.
authz_svc
Returns the authorization service requested by the client that
made the remote procedure call on binding.
Specifying NULL prevents the routine from returning this
parameter. The possible authorization services are as follows:
rpc_c_authz_none
Server performs no authorization. This is valid only
if the authn_svc parameter is rpc_c_authn_none.
rpc_c_authz_name
Server performs authorization based on the client
principal name.
rpc_c_authz_dce
Server performs authorization using the client's DCE
Privilege Attribute Certificate (PAC) sent to the server
with each remote procedure call made with binding.
Generally, access is checked against DCE Access Control
Lists (ACLs).
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
rpc_s_binding_has_no_auth
Binding has no authentication information.
DESCRIPTION
The rpc_binding_inq_auth_client() routine returns authentication and
authorization information associated with the client identified by
binding. The calling server manager routine can use the returned data
for authorization purposes. This call is provided only for
compatibility with pre-1.1 DCE applications. DCE Release 1.1 and
later applications should use the rpc_binding_inq_auth_caller() call.
The RPC runtime allocates memory for the returned server_princ_name
parameter. The server is responsible for calling the
rpc_string_free() routine for the returned parameter string.
For applications in which the client side uses the IDL auto_handle
or implicit_handle attribute, the server side needs to be built with
the IDL explicit_handle attribute specified in the Attribute
Configuration File (ACF). Using explicit_handle provides binding as
the first parameter to each server manager routine.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_inq_auth_info
rpc_binding_set_auth_info
rpc_string_free
3.18 – rpc_binding_inq_auth_info
NAME
rpc_binding_inq_auth_info - Returns authentication and authorization
information from a server binding handle
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
#include <dce/sec_login.h>
void rpc_binding_inq_auth_info(
rpc_binding_handle_t binding,
unsigned_char_t **server_princ_name,
unsigned32 *protect_level,
unsigned32 *authn_svc,
rpc_auth_identity_handle_t *auth_identity,
unsigned32 *authz_svc,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies the server binding handle from which to return the
authentication and authorization information.
Output
server_princ_name
Returns a pointer to the expected principal name of the server
referenced by binding. The content of the returned name and its
syntax is defined by the authentication service in use.
Specifying NULL prevents the routine from returning this
parameter. In this case, the caller does not have to call the
rpc_string_free() routine.
protect_level
Returns the protection level used for remote procedure calls made
with binding. The protection level determines the degree to which
authenticated communications between the client and the server are
protected. Note that the returned level may be different from the
level specified for protect_level on the call to
rpc_binding_set_auth_info(). If the RPC runtime or the RPC
protocol in the bound protocol sequence does not support a
specified level, the level is automatically upgraded to the next
higher supported level.
Specifying NULL prevents the routine from returning this
parameter. The possible protection levels are as follows:
rpc_c_protect_level_default
Uses the default protection level for the specified
authentication service.
rpc_c_protect_level_none
Performs no protection.
rpc_c_protect_level_connect
Performs protection only when the client establishes
a relationship with the server.
rpc_c_protect_level_call
Performs protection only at the beginning of each
remote procedure call when the server receives the
request.
rpc_c_protect_level_pkt
Ensures that all data received is from the expected
client.
rpc_c_protect_level_pkt_integ
Ensures and verifies that none of the data
transferred between client and server has been
modified.
rpc_c_protect_level_pkt_privacy
Performs protection as specified by all of the
previous levels and also encrypt each remote
procedure call parameter value.
authn_svc
Returns the authentication service used for remote procedure calls
made with binding.
Specifying NULL prevents the routine from returning this argument.
The possible authentication services are as follows:
rpc_c_authn_none
No authentication.
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
rpc_c_authn_default
DCE default authentication service.
auth_identity
Returns a handle for the data structure that contains the client's
authentication and authorization credentials. This parameter must
be cast as appropriate for the authentication and authorization
services established via rpc_binding_set_auth_info().
When using the rpc_c_authn_dce_secret authentication service and
any authorization service, this value must be a sec_login_handle_t
obtained from one of the following routines:
+ sec_login_setup_identity()
+ sec_login_get_current_context()
+ sec_login_newgroups()
These routines are described in Chapter 5 of this manual.
Specifying NULL prevents the routine from returning this parameter.
authz_svc
Returns the authorization service used for remote procedure calls
made with binding.
Specifying NULL prevents the routine from returning this
parameter. The possible authorization services are as follows:
rpc_c_authz_none
Server performs no authorization. This is valid only
if the authn_svc parameter is rpc_c_authn_none.
rpc_c_authz_name
Server performs authorization based on the client
principal name.
rpc_c_authz_dce
Server performs authorization using the client's DCE
Privilege Attribute Certificate (PAC) sent to the server
with each remote procedure call made with binding.
Generally, access is checked against DCE Access Control
Lists (ACLs).
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
rpc_s_binding_has_no_auth
Binding has no authentication information.
DESCRIPTION
The rpc_binding_inq_auth_info() routine returns authentication and
authorization information associated with the specified server binding
handle. The calling client associates the authentication and
authorization data with the server binding handle by a prior call to
the rpc_binding_set_auth_info() routine.
The RPC runtime allocates memory for the returned server_princ_name
parameter. The caller is responsible for calling the
rpc_string_free() routine for the returned parameter string.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_set_auth_info
rpc_string_free
3.19 – rpc_binding_inq_object
NAME
rpc_binding_inq_object - Returns the object UUID from a binding handle
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_inq_object( rpc_binding_handle_t binding,
uuid_t *object_uuid,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a client or server binding handle.
Output
object_uuid
Returns the object UUID found in the binding parameter. The
object UUID is a unique identifier for an object for which a
remote procedure call can be made.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings are
as follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
DESCRIPTION
The rpc_binding_inq_object() routine obtains the object UUID
associated with a client or server binding handle. If no object
UUID has been associated with the binding handle, this routine
returns a nil UUID.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_set_object
3.20 – rpc_binding_reset
NAME
rpc_binding_reset - Resets a server binding handle
Used by client or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_reset( rpc_binding_handle_t binding,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies the server binding handle to reset.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_binding_reset() routine disassociates a server instance from
the server binding handle specified in the binding parameter. This
routine removes the endpoint portion of the server address in the
binding handle as well as any other server instance information in the
binding handle. The host portion of the server address remains
unchanged. The result is a partially bound server binding handle.
This binding handle can rebind to another server instance on the
previous host when it is later used to make a remote procedure call.
The rpc_intro reference page contains an explanation of partially and
fully bound binding handles.
This routine does not affect any authentication information for the
binding parameter.
Suppose that a client can be serviced by any compatible server
instance on the host specified in the binding handle. Then, the
client can call the rpc_binding_reset() routine before making a
remote procedure call using the binding handle specified in binding.
When the client makes the next remote procedure call using the reset
server binding handle in binding, the client's RPC runtime uses a
well-known endpoint from the client's interface specification, if any.
Otherwise, the client's RPC runtime automatically communicates with
the DCE Host Daemon (dced) on the specified remote host, to obtain the
endpoint of a compatible server from the local endpoint map. If a
compatible server is located, the RPC runtime updates binding with a
new endpoint.
However, if a compatible server is not located, the client's remote
procedure call fails. If the failed call uses a connection protocol
(ncacn), it receives the rpc_s_endpoint_not_found status code. If
the failed call uses a datagram protocol (ncadg), it receives the
rpc_s_comm_failure status code.
If a server application wants to be available to clients making a
remote procedure call on a reset binding handle, it registers all
binding handles by calling rpc_ep_register() or
rpc_ep_register_no_replace(). If, however, the IDL-generated file
contains endpoint address information, then the application does not
have to call either of these two routines.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_register_no_replace
3.21 – rpc_binding_server_from_client
NAME
rpc_binding_server_from_client - Converts a client binding handle
to a server binding handle
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_server_from_client(
rpc_binding_handle_t client_binding,
rpc_binding_handle_t *server_binding,
unsigned32 *status );
PARAMETERS
Input
client_binding
Specifies the client binding handle to convert to a server
binding handle.
Output
server_binding
Returns a server binding handle.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_cant_getpeername
Cannot get peer name.
rpc_s_connection_closed
Connection closed.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding.
DESCRIPTION
When a remote procedure call arrives at a server, the RPC runtime
creates a client binding handle to refer to information about the
calling client (client binding information). The RPC runtime
passes the client binding handle to the called remote procedure as
the first input argument (which uses the handle_t type).
The rpc_binding_server_from_client() routine converts client binding
information into server binding information corresponding to the
client's system. When calling this routine, the called remote
procedure specifies the client binding handle, and the routine
returns a partially bound server binding handle (that is, the newly
constructed server binding information contains a network address
for the client's system, but lacks an endpoint). The server binding
information also lacks authentication information, but the called
procedure can add it by calling rpc_binding_set_auth_info(). The
object UUID from the client binding information remains.
The rpc_binding_server_from_client() routine is relevant when a
called remote procedure (the first remote procedure) needs to make
its own remote procedure call (a nested procedure call) to a second
remote procedure offered by a server on the system of the client
that called the first remote procedure (that is, the original
client). The partially bound server binding handle returned by the
rpc_binding_server_from_client() routine ensures that a nested call
requests the second remote procedure on the original client's system.
In a multithreaded RPC application, the second remote procedure can
belong to a server that shares the original client's address space
(that is, the server and client can operate jointly as a
server/client instance). If the original client belongs to a
server/client instance and the application requires the nested call
to execute in that instance, the application must guarantee that the
nested remote procedure call uses one of the instances' endpoints.
An application can provide this guarantee by meeting any of the
following conditions:
+ The interface possesses its own well-known endpoints, and
the server elects to use these interface-specific endpoints
(by calling rpc_server_use_protseq_if() or
rpc_server_use_all_protseqs_if()).
+ The server uses server-specific endpoints, and the interface is
offered by only one server/client instance per system.
To use server-specific endpoints, a server either requests
dynamic endpoints (by calling rpc_server_use_protseq() or
rpc_server_use_all_protseqs()) or specifies its own well-known
endpoints (by calling rpc_server_use_protseq_ep()). The server
must also register its server-specific endpoints in the local
endpoint map (by calling rpc_ep_register()).
+ The original client sets an object UUID into the server binding
information of the first call (by calling
rpc_binding_set_object()); the object UUID identifies the
server/client instance. The client can obtain the object UUID
from the list of object UUIDs used to register the endpoints of
the server/client instance. The client must select an object
UUID that belongs exclusively to its instance.
Server binding information containing an object UUID impacts
the selection of a manager for a remote procedure call; see the
OSF DCE Application Development Guide for a description of
manager selection. The object UUID can either identify a
particular resource offered by the companion server or, used as
an instance UUID, the object UUID can identify the original
client's server/client instance.
The object UUID is passed in the first remote procedure call as
part of the client binding information and is retained in the
server binding information. This server binding information is
newly constructed by the rpc_binding_server_from_client()
routine. When the second remote procedure call arrives at the
original client's system, the DCE Host daemon uses the object
UUID to look for associated endpoints in the local endpoint map.
To ensure that the object UUID is associated with the endpoints
of the original server/client instance, the server must complete
the following steps:
1. Obtain the UUID (for example, by calling uuid_create()).
2. Specify the UUID as part of registering endpoints for the
interface of the second remote procedure (by calling
rpc_ep_register() or rpc_ep_register_no_replace()).
If the second remote procedure call will be routed to a manager
of a non-nil type, then the server must also do the following:
1. Specify the type for the manager that implements that
interface (by calling rpc_server_register_if()).
2. Set the object UUID to the same type as the manager (by
calling rpc_object_set_type()).
+ The first remote procedure call contains a distinct call argument
used by the original client to pass server information that
identifies its server/client instance.
The first remote procedure call uses this information to route
the second remote procedure call to the original server/client
instance. For example, server information can be as follows:
- A fully bound string binding that identifies the client's
server/client instance. If the first remote procedure
receives this string binding, calling the
rpc_binding_server_from_client routine is unnecessary.
Instead, the first remote procedure requests a server
binding handle for the string binding (by calling
rpc_binding_from_string_binding()).
- An object UUID that is associated in the endpoint map with
one or more endpoints of the original server/client instance.
The client can obtain the object UUID from the list of object
UUIDs used to register the endpoints of the server/client
instance. The client must select an object UUID that belongs
exclusively to its instance, and pass that UUID as a call
argument. After calling the rpc_binding_server_from_client()
routine, add the object UUID from the call argument to the
newly constructed server binding information (by calling
rpc_binding_set_object()).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_free
rpc_binding_set_object
rpc_ep_register
rpc_ep_register_no_replace
Books: DCE OSF Application Development Guide.
3.22 – rpc_binding_set_auth_info
NAME
rpc_binding_set_auth_info - Sets authentication and authorization
information for a server binding handle
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
#include <dce/sec_login.h>
void rpc_binding_set_auth_info(
rpc_binding_handle_t binding,
unsigned_char_t *server_princ_name,
unsigned32 protect_level,
unsigned32 authn_svc,
rpc_auth_identity_handle_t auth_identity,
unsigned32 authz_svc,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies the server binding handle for which to set the
authentication and authorization information.
server_princ_name
Specifies the principal name of the server referenced by binding.
The content of the name and its syntax is defined by the
authentication service in use.
A client that does not know the server principal name can call
the rpc_mgmt_inq_server_princ_name() routine to obtain the
principal name of a server that is registered for the required
authentication service. Using a principal name obtained in this
way means that the client is interested in one-way authentication.
In other words, it means that the client does not care which
server principal received the remote procedure call request. The
server, though, still verifies that the client is who the client
claims to be.
protect_level
Specifies the protection level for remote procedure calls made
using binding. The protection level determines the degree to
which authenticated communications between the client and the
server are protected by the authentication service specified by
authn_svc.
If the RPC runtime or the RPC protocol in the bound protocol
sequence does not support a specified level, the level is
automatically upgraded to the next higher supported level.
The possible protection levels are as follows:
rpc_c_protect_level_default
Uses the default protection level for the specified
authentication service. The default protection
level for the DCE shared-secret key authentication
service is rpc_c_protect_level_pkt_integ.
rpc_c_protect_level_none
Performs no authentication: tickets are not
exchanged, session keys are not established, client
PACs or names are not certified, and transmissions
are in the clear. Note that although uncertified
PACs should not be trusted, they may be useful for
debugging, tracing, and measurement purposes.
rpc_c_protect_level_connect
Performs protection only when the client establishes
a relationship with the server.
rpc_c_protect_level_call
Performs protection only at the beginning of each
remote procedure call when the server receives the
request. This level does not apply to remote
procedure calls made over a connection-based
protocol sequence (that is, ncacn_ip_tcp). If this
level is specified and the binding handle uses a
connection-based protocol sequence, the routine uses
the rpc_c_protect_level_pkt level instead.
rpc_c_protect_level_pkt
Ensures that all data received is from the expected
client.
rpc_c_protect_level_pkt_integ
Ensures and verifies that none of the data
transferred between client and server has been
modified. This is the highest protection level that
is guaranteed to be present in the RPC runtime.
rpc_c_protect_level_pkt_privacy
Performs protection as specified by all of the
previous levels and also encrypt each remote
procedure call argument value. This is the highest
protection level, but it may not be available in
the RPC runtime.
authn_svc
Specifies the authentication service to use. The exact level of
protection provided by the authentication service is specified
by the protect_level parameter. The supported authentication
services are as follows:
rpc_c_authn_none
No authentication: no tickets are exchanged, no
session keys established, client PACs or names are
not transmitted, and transmissions are in the clear.
Specify rpc_c_authn_none to turn authentication off
for remote procedure calls made using binding.
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_default
DCE default authentication service. The current
default authentication service is DCE shared-secret
key; therefore, specifying rpc_c_authn_default is
equivalent to specifying rpc_c_authn_dce_secret.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
rpc_c_authn_winnt
Authentication via Microsoft NT Lan Manager (only
available on Windows NT and OpenVMS). This allows
OpenVMS applications to authenticate with a Windows
NT domain security server.
auth_identity
Specifies a handle for the data structure that contains the
client's authentication and authorization credentials
appropriate for the selected authentication and authorization
services. When using the rpc_c_authn_dce_secret authentication
service and any authorization service, this value must be a
sec_login_handle_t obtained from one of the following routines:
+ sec_login_setup_identity()
+ sec_login_get_current_context()
+ sec_login_newgroups()
+ rpc_winnt_set_auth_identity
Specify NULL to use the default security login context for the current
address space.
authz_svc
Specifies the authorization service implemented by the server
for the interface of interest. The validity and trustworthiness
of authorization data, like any application data, is dependent on
the authentication service and protection level specified. The
supported authorization services are as follows:
rpc_c_authz_none
Server performs no authorization. This is valid only if
the authn_svc parameter is rpc_c_authn_none, specifying
that no authentication is being performed.
rpc_c_authz_name
Server performs authorization based on the client
principal name. This value cannot be used if authn_svc
is rpc_c_authn_none.
rpc_c_authz_dce
Server performs authorization using the client's DCE
Privilege Attribute Certificate (PAC) sent to the
server with each remote procedure call made with
binding. Generally, access is checked against DCE
Access Control Lists (ACLs). This value cannot be
used if authn_svc is rpc_c_authn_none.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
rpc_s_unknown_authn_service
Unknown authentication service.
rpc_s_authn_authz_mismatch
Requested authorization service is not supported by
the requested authentication service.
rpc_s_unsupported_protect_level
Requested protection level is not supported.
DESCRIPTION
The rpc_binding_set_auth_info() routine sets up the specified server
binding handle so that it can be used to make authenticated remote
procedure calls that include authorization information.
Unless a client calls rpc_binding_set_auth_info() with the parameters
to set establish authentication and authorization methods, all remote
procedure calls made on the binding binding handle are unauthenti-
cated.Some authentication services (authn_svc) may need to
communicate with the Security service to perform this operation.
Otherwise, they may receive the rpc_s_comm_failure status.
The authn_svc parameter specifies the authentication service to use.
Since currently, there is only one available authentication service
(DCE shared-secret key), the parameter currently functions to specify
whether or not rpc calls will be authenticated and client PACs
certified. If authentication is chosen, the protect_level parameter
can specify a variety of protection levels, ranging from no
authentication to the highest level of authentication and encryption.
If the protect_level parameter is set to rpc_c_protect_level_none, no
authentication is performed, regardless of the authentication service
chosen.
The authz_svc parameter specifies the authorization service to use.
If no authentication has been chosen (authn_svc of rpc_c_authn_none),
then no authorization (authz_svc of rpc_c_authz_none) must be chosen
as well. If authentication will be performed, you have two choices
for authorization: name-based authorization and DCE authorization.
The use of name based_authorization, which provides a server with a
client's principal name, is not recommended. DCE authorization uses
PACs, a trusted mechanism for conveying client authorization data to
authenticated servers. PACs are designed to be used with the DCE ACL
facility.
Whether the call actually wakes up in the server manager code or is
rejected by the runtime depends on following conditions:
+ If the client specified no authentication, then none is attempted
by the RPC runtime.The call wakes up in the manager code whether
the server specified authentication or not. This permits both
authenticated and unauthenticated clients to call authenticated
servers. When the manager receives an unauthenticated call, it
needs to make a decision about how to proceed.
+ If the client specified DCE secret key authentication and the
server specified no authentication, then the runtime will fail
the call, and it will never reach the manager routine.
+ If both client and server specified DCE secret key
authentication, then authentication will be carried out
by the RPC runtime transparently. Whether the call reaches
the server manager code or is rejected by the runtime
depends on whether the authentication succeeded.
Although the RPC runtime is responsible any authentication that is
carried out, the fact that the runtime will always permit
unauthenticated clients to reach the manager code means that a
manager access function typically does need to make an
authentication check. When the manager access routine calls
rpc_binding_inq_auth_client() it needs to check for a status of
rpc_s_binding_has_no_auth. In this case, the client has specified
no authentication and the manager access function needs to make an
access decision based on this fact. Note that in such a case, no
meaningful authentication or authorization information is returned
from rpc_binding_inq_auth_client().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_inq_auth_client
rpc_binding_inq_auth_info
rpc_mgmt_inq_dflt_protect_level
rpc_mgmt_inq_server_princ_name
sec_login_get_current_context
sec_login_newgroups
sec_login_setup_identity
3.23 – rpc_binding_set_object
NAME
rpc_binding_set_object - Sets the object UUID value into a server
binding handle.
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_set_object( rpc_binding_handle_t binding,
uuid_t *object_uuid,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies the server binding into which parameter object_uuid is
set. Supply NULL to specify a nil UUID for this parameter.
object_uuid
Specifies the UUID of the object serviced by the server specified
in the binding parameter. The object UUID is a unique identifier
for an object for which a remote procedure call can be made.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings are
as follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_binding_set_object() routine associates an object UUID with
a server binding handle. This operation replaces the previously
associated object UUID with the UUID in the object_uuid parameter.
To set the object UUID to the nil UUID, specify NULL or the nil UUID
for the object_uuid parameter.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_from_string_binding
rpc_binding_inq_object
3.24 – rpc_binding_to_string_binding
NAME
rpc_binding_to_string_binding - Returns a string representation of
a binding handle
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_to_string_binding( rpc_binding_handle_t binding,
unsigned_char_t **string_binding,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a client or server binding handle to convert to a
string representation of a binding handle.
Output
string_binding
Returns a pointer to the string representation of the binding
handle specified in the binding parameter.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_cant_getpeername
Cannot get peer name.
rpc_s_connection_closed
Connection closed.
rpc_s_invalid_binding
Invalid binding handle.
DESCRIPTION
The rpc_binding_to_string_binding() routine converts a client or
server binding handle to its string representation.
The RPC runtime allocates memory for the string returned in the
string_binding parameter. The application calls the rpc_string_free()
routine to deallocate that memory.
If the binding handle in the binding parameter contains a nil object
UUID, the object UUID field is not included in the returned string.
To parse the returned string_binding parameter, call
rpc_string_binding_parse().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_from_string_binding
rpc_string_binding_parse
rpc_string_free
3.25 – rpc_binding_vector_free
NAME
rpc_binding_vector_free - Frees the memory used to store a vector
and binding handles
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_binding_vector_free( rpc_binding_vector_t **binding_vector,
unsigned32 *status );
PARAMETERS
Input/Output
binding_vector
Specifies the address of a pointer to a vector of server binding
handles. On return the pointer is set to NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_arg
Invalid argument.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_binding_vector_free() routine frees the memory used to store
a vector of server binding handles. The freed memory includes both
the binding handles and the vector itself.
A server obtains a vector of binding handles by calling
rpc_server_inq_bindings(). A client obtains a vector of binding
handles by calling rpc_ns_binding_lookup_next(). Call
rpc_binding_vector_free() if you have used either of these routines.
The rpc_binding_free() routine frees individual elements of the
vector. If an element is freed with this routine, the NULL element
entry replaces it; rpc_binding_vector_free() ignores such an entry.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_free
rpc_ns_binding_lookup_next
rpc_server_inq_bindings
3.26 – rpc_cs_binding_set_tags
NAME
rpc_cs_binding_set_tags - Places code set tags into a server binding
handle
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_cs_binding_set_tags( rpc_binding_handle_t *binding,
unsigned32 sending_tag,
unsigned32 desired_receiving_tag,
unsigned16 sending_tag_max_bytes,
error_status_t *status );
PARAMETERS
Input/Output
binding
On input, specifies the server binding handle to modify with tag
information. This handle is the binding handle returned by the
rpc_ns_binding_import_next() or rpc_ns_binding_select() routine.
On output, returns the server binding handle modified with code
set tag information. The server stub retrieves the tag information
from the binding handle and uses it to invoke the appropriate
buffer sizing and code set conversion routines.
Input
sending_tag
Specifies the code set value for the code set in which client
data to be sent to the server is to be encoded. If the client
is not sending any data, set this value to the client's current
code set. This step prevents the code set conversion routine
from being invoked.
desired_receiving_tag
Specifies the code set value for the code set in which the client
prefers data to be encoded when sent back from the server. If
the client is not planning to receive any data from the server,
set this value to the server's current code set. This step
prevents the code set conversion routine from being invoked.
sending_tag_max_bytes
Specifies the maximum number of bytes that a code set requires
to encode one character. The value is the c_max_bytes value
associated with the code set value (c_set) used as the
sending_tag value.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok
rpc_s_no_memory
The routine can also return status codes generated by the
rpc_rgy_get_codesets() routine.
DESCRIPTION
The rpc_cs_binding_set_tags() routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment. These routines are used
to enable "automatic" code set conversion between client and server
for character representations that are not part of the DCE Portable
Character Set.
Client applications use the rpc_cs_binding_set_tags() routine to add
code sets tag information to the binding handle of a compatible
server. The tag information specified in the routine is usually
obtained from a character and code sets evaluation routine (which is
typically a user-written routine).
The sending_tag value identifies the code set encoding that the client
is using to send international character data to the server. The
desired_receiving_tag value indicates to the server the code set that
the client prefers the server to use when sending return international
character data. The sending_tag_max_bytes value is the number of bytes
the sending code set uses to encode one character.
Client applications that use the rpc_cs_eval_with_universal() or
rpc_cs_eval_without_universal() routines do not need to call this
routine because these routines set tag information in the server
binding handle as part of their operation. Application developers
who are writing their own character and code sets evaluation routines
need to include code that sets tags in a server binding handle. The
rpc_cs_binding_set_tags() routine provides this function and can be
used in user-written evaluation routines, or alone if the application
does not need to perform evaluation. In this case, the routine
provides a short cut for application programmers whose applications
do not need to evaluate for character and code set compatibility.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_cs_eval_with_universal
rpc_cs_eval_without_universal
rpc_cs_get_tags
3.27 – rpc_cs_char_set_compat_check
NAME
rpc_cs_char_set_compat_check - Evaluates character set compatibility
between a client and a server.
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_cs_char_set_compat_check(
unsigned32 client_rgy_code_set_value,
unsigned32 server_rgy_code_set_value,
error_status_t *status );
PARAMETERS
Input
client_rgy_code_set_value
The registered hexadecimal value that uniquely identifies the code
set that the client is using as its local code set.
server_rgy_code_set_value
The registered hexadecimal value that uniquely identifies the code
set that the server is using as its local code set.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok
rpc_s_ss_no_compat_charsets
The routine can also return status codes from the dce_cs_rgy_to_loc()
routine.
DESCRIPTION
The rpc_cs_char_set_compat_check() routine belongs to a set of DCE
RPC routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment.
The rpc_cs_char_set_compat_check() routine provides a method for
determining character set compatibility between a client and a
server; if the server's character set is incompatible with that of
the client, then connecting to that server is most likely not
acceptable, since massive data loss would result from such a
connection.
The RPC routines that perform character and code sets evaluation use
the rpc_cs_char_set_compat_check() routine in their character sets
and code sets compatibility checking procedure. The routine takes the
registered integer values that represent the code sets that the client
and server are currently using and calls the code set registry to
obtain the registered values that represent the character set(s) that
the specified code sets support. If both client and server support
just one character set, the routine compares client and server
registered character set values to determine whether or not the sets
are compatible. If they are not, the routine returns the status
message rpc_s_ss_no_compat_charsets.
If the client and server support multiple character sets, the
routine determines whether at least two of the sets are compatible.
If two or more sets match, the routine considers the character sets
compatible, and returns a success status code to the caller.
Client and server applications that use the DCE RPC code sets
evaluation routines rpc_cs_eval_with_universal() and
rpc_cs_eval_without_universal() do not need to call this routine
explicitly because these DCE RPC routines call it on their behalf.
Client applications that do not use the DCE RPC code sets evaluation
routines can use the rpc_cs_char_set_compat_check() routine in their
code sets evaluation code as part of their procedure for determining
character and code set compatibility with a server.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_cs_eval_with_universal
rpc_cs_eval_without_universal
rpc_cs_get_tags
rpc_ns_mgmt_read_codesets
rpc_rgy_get_codesets
3.28 – rpc_cs_eval_with_universal
NAME
rpc_cs_eval_with_universal - Evaluates a server's supported
character sets and code sets during
the server binding selection process
Used indirectly by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_cs_eval_with_universal( rpc_ns_handle_t binding_handle,
idl_void_p_t eval_args,
idl_void_p_t *context );
PARAMETERS
Input
binding_handle
The server binding handle.
eval_args
An opaque data type that contains matching criteria that the
routine uses to perform character and code sets compatibility
evaluation.
Input/Output
context
An opaque data type that contains search context to perform
character and code sets compatibility evaluation. The routine
returns the result of the evaluation in a field within context.
DESCRIPTION
The rpc_cs_eval_with_universal() routine is a DCE RPC character and
code sets evaluation routine that can be added to an import context.
The routine provides a mechanism for a client application that is
passing character data in a heterogeneous character set and code sets
environment to evaluate a server's character and code sets
compatibility before establishing a connection with it.
Client applications do not call rpc_cs_eval_with_universal() directly.
Instead, they add it to the import context created by the
rpc_ns_binding_import_begin() routine by calling the routine
rpc_ns_import_ctx_add_eval() and specifying the routine name and the
RPC server entry name to be evaluated. When the client application
calls the rpc_ns_binding_import_next() routine to import compatible
binding handles for servers, this routine calls
rpc_cs_eval_with_universal(), which applies client-server code sets
compatibility checking as another criteria for compatible binding
selection.
The rpc_cs_eval_with_universal() routine directs the
rpc_ns_binding_import_next() routine to reject servers with
incompatible character sets. If client and server character sets
are compatible, but their supported code sets are not, the routine
establishes tags that direct the client and/or server stubs to
convert character data to the user-defined (if any) or default
intermediate code set, which is the ISO10646 (or "universal") code
set.
Application programmers need not pay attention to the arguments of
this routine. They only need to use the rpc_ns_import_ctx_add_eval()
to set the routine, for example:
rpc_ns_import_ctx_add_eval( &import_context,
rpc_c_eval_type_codesets,
(void *) nsi_entry_name,
rpc_cs_eval_with_universal,
NULL,
&status );
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_cs_eval_without_universal
rpc_cs_get_tags
rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_import_ctx_add_eval
rpc_ns_mgmt_handle_set_exp_age
3.29 – rpc_cs_eval_without_universal
NAME
rpc_cs_eval_without_universal - Evaluates a server's supported
character sets and code sets
during the server binding
selection process
Used indirectly by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_cs_eval_without_universal( rpc_ns_handle_t binding_handle,
idl_void_p_t eval_args,
idl_void_p_t *context );
PARAMETERS
Input
binding_handle
The server binding handle.
eval_args
An opaque data type that contains matching criteria that the
routine uses to perform code sets compatibility evaluation.
Input/Output
context
An opaque data type that contains search context to perform
character and code sets compatibility evaluation. The
routine returns the result of the evaluation in a field
within context.
DESCRIPTION
The rpc_cs_eval_without_universal() routine is a DCE RPC character
and code sets evaluation routine that can be added to an import
context. The routine provides a mechanism for a client application
that is passing character data in a heterogeneous character set and
code sets environment to evaluate a server's character and code sets
compatibility before establishing a connection with it.
Client applications do not call rpc_cs_eval_without_universal()
directly. Instead, they add it to the import context created by
the rpc_ns_binding_import_begin() routine by calling the routine
rpc_ns_import_ctx_add_eval() and specifying the routine name and
the RPC server entry name to be evaluated. When the client
application calls the rpc_ns_binding_import_next() routine to import
compatible binding handles for servers, this routine calls
rpc_cs_eval_without_universal(), which applies client-server code
sets compatibility checking as another criteria for compatible
binding selection.
The rpc_cs_eval_without_universal() routine directs the
rpc_ns_binding_import_next() routine to reject servers with
incompatible character sets. The routine also directs the
rpc_ns_binding_import_next() routine to reject servers whose
supported code sets are incompatible with the client's supported
code sets; that is, it does not resort to using an intermediate
code set as a last resort.
Application programmers need not pay attention to the arguments of
this routine. They only need to use the rpc_ns_import_ctx_add_eval()
to set the routine, for example:
rpc_ns_import_ctx_add_eval( &import_context,
rpc_c_eval_type_codesets,
(void *) nsi_entry_name,
rpc_cs_eval_without_universal,
NULL,
&status );
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_cs_get_tags
rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_import_ctx_add_eval
rpc_ns_mgmt_handle_set_exp_age
3.30 – rpc_cs_get_tags
NAME
rpc_cs_get_tags - Retrieves code set tags from a binding handle
Used by client and server applications.
SYNOPSIS
#include <dce/codesets_stub.h>
void rpc_cs_get_tags( rpc_binding_handle_t binding,
boolean32 server_side,
unsigned32 *sending_tag,
unsigned32 *desired_receiving_tag,
unsigned32 *receiving_tag,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain the code
set tag information. When called from the client stub, this value
is the binding handle of a compatible server returned by the
rpc_ns_binding_import_next() or rpc_ns_binding_select() routines.
When called from the server stub, this value is a pointer to the
tag information that the client stub passed in the RPC call.
server_side
Indicates whether a client stub or a server stub is calling the
routine.
desired_receiving_tag
(Server stub only) Specifies the code set value for the code set
in which the client prefers data to be encoded when sent back from
the server. The client stub passes this value in the RPC call. If
the routine is retrieving code set tags for an operation that does
not specify a desired receiving tag parameter (the cs_drtag ACF
parameter attribute has not been applied to one of the operation's
parameters), this value is NULL.
Output
sending_tag
(Client stub only) Specifies the code set value for the code set
in which client data to be sent to the server is to be encoded.
If the routine is retrieving code set tags for an operation that
does not specify a sending tag parameter (the cs_stag ACF
parameter attribute has not been applied to one of the operation's
parameters), this value is NULL.
desired_receving_tag
(Client stub only) Specifies the code set value for the code set
in which the client prefers to receive data sent back to it from
the server. If the routine is retrieving code set tags for an
operation that does not specify a desired receiving tag parameter
(the cs_drtag ACF parameter attribute has not been applied to one
of the operation's parameters), this value is NULL.
receiving_tag
(Server stub only) Specifies the code set value for the code set
in which the server is to encode data to be sent back to the
client. If the routine is retrieving code set tags for an
operation that does not specify a receiving tag parameter (the
cs_rtag ACF parameter attribute has not been applied to one of
the operation's parameters), this value is NULL.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The server cannot handle the data in the code set
that the client has specified. This status code
will be returned if the application performs
code set compatibility evaluation in the server
stub.
rpc_s_ss_invalid_codeset_tag
The result of the client-side evaluation used an
invalid code set tag.
If code set compatibility evaluation is performed, error values
can also be returned from rpc_rgy_get_codesets(),
rpc_ns_binding_inq_entry_name(), and rpc_ns_mgmt_read_codesets().
DESCRIPTION
The rpc_cs_get_tags() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The rpc_cs_get_tags() routine is a DCE RPC routine that RPC stubs can
use to retrieve the code set values to be used to "tag" international
character data to be sent over the network. In general, the code set
values to be used as tags are determined by a character and code sets
evaluation routine, which is invoked from the client application code.
However, application programmers can use other methods to establish
values for code set tags.
RPC stubs call the rpc_cs_get_tags() routine before they call the
buffer sizing routines *_net_size() and the code set conversion
routines _netcs(). The rpc_cs_get_tags() routine provides the stubs
with code set values to use as input to the buffer sizing routines
(to determine whether or not buffer storage needs to be allocated for
conversion) and as input to the code set conversion routines (to
determine whether conversion is necessary, and if so, which host code
set converter to invoke).
Client and server stubs call the rpc_cs_get_tags() routine before
they marshall any data. When called from the client stub, the boolean
value server_side is set to FALSE to indicate that the client stub has
invoked the routine. The binding handle is the handle to a compatible
server returned by the rpc_ns_binding_import_next() or
rpc_ns_binding_select() routines. If the client has added a code sets
evaluation routine to the binding import procedure (by calling the
routine rpc_ns_import_ctx_add_eval()), the binding handle will contain
the conversion method and the code set values to set for the client's
sending tag and desired receiving tag. If the binding handle does not
contain the results of an evaluation, the rpc_cs_get_tags() routine
will perform the character/code sets evaluation within the client stub
and set the client code set tag values itself.
On the client side, the output of the routine is the code set value
that represents the client's sending tag and the code set value that
represents the client's desired receiving tag. If the conversion
method is "client makes it right" (CMIR), the sending tag and desired
receiving tags will be set to the code set value of the server's
local code set. If the conversion method is "server makes it right"
(SMIR), the sending tag and desired receiving tag will be set to the
client's local code set value. If the conversion method is "receiver
makes it right" (RMIR), the sending tag is the client's code set, and
the desired receiving tag is the server's code set.
When called from the server stub, the boolean value server_side is
set to TRUE to indicate that the server stub has invoked the routine.
The binding handle is a pointer to the tag data sent by the client
stub.
The server stub specifies the code set value given in the client's
desired receiving tag as input to the routine. The rpc_cs_get_tags()
routine sets the code set value in desired_receiving_tag to
receiving_tag and returns this value as output to the server stub.
The server stub will then use the code set value in receiving_tag as
the code set to use for data it sends back to the client.
Application programmers who want their applications to use the
rpc_cs_get_tags() routine to retrieve code set tag information as
part of the automatic code set conversion process specify the
routine name as the argument to the ACF attribute cs_tag_rtn when
developing their internationalized RPC application.
Application programmers can also write their own code set tags
retrieval routine that RPC stubs can call; in this case, they specify
the name of this routine as the argument to the ACF attribute instead
of specifying the DCE RPC routine rpc_cs_get_tags(). Application
programmers can also use the automatic code conversion mechanism, but
design their applications so that the code set tags are set explicitly
in the application instead of in the stubs.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: cs_byte_from_netcs
cs_byte_local_size
cs_byte_net_size
cs_byte_to_netcs
wchar_t_from_netcs
wchar_t_local_size
wchar_t_net_size
wchar_t_to_netcs
Books: OSF DCE Application Development Guide-Core Components.
3.31 – rpc_ep_register
NAME
rpc_ep_register - Adds to, or replaces, server address information
in the local endpoint map
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ep_register( rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned_char_t *annotation,
unsigned32 *status );
PARAMETERS
Input
if_handle
Specifies an interface specification to register with the local
endpoint map.
binding_vec
Specifies a vector of binding handles over which the server can
receive remote procedure calls.
object_uuid_vec
Specifies a vector of object UUIDs that the server offers. The
server application constructs this vector.
Supply the value NULL to indicate there are no object UUIDs to
register.
annotation
Defines a character string comment applied to each cross product
element added to the local endpoint map. The string can be up to
64 characters long, including the NULL terminating character.
Specify NULL or the string \0 if there is no annotation string.
The string is used by applications for informational purposes
only. The RPC runtime does not use this string to determine
which server instance a client communicates with, or for
enumerating endpoint map elements.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
ept_s_cant_access
Error reading endpoint database.
ept_s_cant_create
Error creating endpoint database.
ept_s_cant_perform_op
Cannot perform requested operation.
ept_s_database_invalid
Endpoint map database invalid.
ept_s_invalid_entry
Invalid database entry.
ept_s_update_failed
Update failed.
rpc_s_comm_failure
Communications failure.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_no_bindings
No bindings.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_ep_register() routine adds elements to, or replaces elements
in, the local host's endpoint map.
Each element in the local endpoint map logically contains the
following:
+ Interface ID, consisting of an interface UUID and versions
(major and minor)
+ Binding information
+ Object UUID (optional)
+ Annotation (optional)
A server uses this routine, instead of rpc_ep_register_no_replace(),
when only a single instance of the server runs on the server's host.
Use this routine if, at any time, no more than one server instance
offers the same interface UUID, object UUID, and protocol sequence.
When local endpoint map elements are not replaced, obsolete elements
accumulate each time a server instance stops running without calling
rpc_ep_unregister(). Periodically the DCE Host Daemon identifies
these obsolete elements and removes them. However, during the time
between these removals the obsolete elements increase the chance that
a client will receive endpoints to nonexistent servers. The client
then wastes time trying to communicate with these servers before
obtaining another endpoint.
Using this routine to replace any existing local endpoint map elements
reduces the chance that a client will receive the endpoint of a
nonexistent server instance.
Suppose an existing element in the local endpoint map matches the
interface UUID, binding information exclusive of the endpoint, and
object UUID of an element this routine provides. The routine changes
the endpoint map according to the elements' interface major and minor
version numbers, as shown in the following table:
Existing Element Relationship Provided Element Routine's Action
______________________________________________________________________
Major version # Not equal to Major version # Ignores minor ver-
sion number rela-
tionship and adds
a new endpoint map
element. The
existing element
remains unchanged.
Major version # Equal to Major version # Acts according to
the minor version
number relation-
ship.
Minor version # Equal to Minor version # Replaces the end-
point of the
existing element
based on the pro-
vided information.
Minor version # Less than Minor version # Replaces the
existing element
based on the pro-
vided information.
Minor version # Greater than Minor version # Ignores the pro-
vided information.
The existing ele-
ment remains
unchanged.
For example, suppose under these circumstances that the existing
interface version number is 1.3 (major.minor) and the provided
version number is 2.0. The routine adds a new endpoint map element
with interface version number 2.0 and does not change the element
with version number 1.3. However, if the existing interface version
number is 1.5 and the provided version number is 1.4, the routine
does not change the endpoint map.
A server program calls this routine to register endpoints that have
been specified by calling any of the following routines:
+ rpc_server_use_all_protseqs()
+ rpc_server_use_protseq()
+ rpc_server_use_protseq_ep()
A server that calls only the rpc_server_use_all_protseqs_if() or
rpc_server_use_protseq_if() routines does not need to call this
routine. In such cases, the client's runtime uses an endpoint from
the client's interface specification to fill in a partially bound
binding handle. However, it is recommended that you also register
well-known endpoints that the server specifies (registering endpoints
from interface definitions is unnecessary).
If the server also exports to the name service database, the server
calls this routine with the same if_handle, binding_vec and
object_uuid_vec parameters as the server uses when calling the
rpc_ns_binding_export() routine.
The rpc_ep_register() routine communicates with the DCE Host Daemon
(dced), which in turn communicates with the local endpoint map. The
routine communicates using one of the protocol sequences specified in
one of the binding handles in binding_vec. Attempting to register a
binding that specifies a protocol sequence that the DCE Host daemon
is not listening on results in the failure of rpc_ep_register(). The
routine indicates this failure by placing the value rpc_s_comm_failure
into status.
For information about how the endpoint map service selects an element
for an interface ID and an object UUID, see the RPC information in the
OSF DCE Application Development Guide. This guide explains how the
endpoint map service searches for the endpoint of a server that is
compatible with a client. If the client supplies a non-nil object
UUID that is not in the endpoint map, or the client supplies a nil
object UUID, the search can succeed, but only if the server has
registered a nil object UUID using the rpc_ep_register() or
rpc_ep_register_no_replace() routines. The object_uuid_vec parameter
can contain both nil and non-nil object UUIDs for the routine to
place into endpoint map elements.
For an explanation of how a server can establish a client/server
relationship without using the local endpoint map, see the explanation
of a string binding in the rpc_intro reference page.
This routine creates a cross product from the if_handle, binding_vec
and object_uuid_vec parameters, and adds each element in the cross
product as a separate registration in the local endpoint map. If you
supply NULL to object_uuid_vec, the corresponding elements in the
cross product contain a nil object UUID.
For example, suppose that if_handle has the value ifhand, binding_vec
has the values b1, b2, b3, and object_uuid_vec has the values u1, u2,
u3, u4.The resulting 12 elements in the cross product are as follows:
(ifhand,b1,u1) (ifhand,b1,u2) (ifhand,b1,u3) (ifhand,b1,u4)
(ifhand,b2,u1) (ifhand,b2,u2) (ifhand,b2,u3) (ifhand,b2,u4)
(ifhand,b3,u1) (ifhand,b3,u2) (ifhand,b3,u3) (ifhand,b3,u4)
(An annotation string is part of each of these 12 elements.)
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register_no_replace
rpc_ep_resolve_binding
rpc_ep_unregister
rpc_mgmt_ep_unregister
rpc_ns_binding_export
rpc_server_inq_bindings
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
Books: OSF DCE Application Development Guide.
3.32 – rpc_ep_register_no_replace
NAME
rpc_ep_register_no_replace - Adds to server address information
in the local endpoint map
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ep_register_no_replace( rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned_char_t *annotation,
unsigned32 *status );
PARAMETERS
Input
if_handle
Specifies an interface specification to register with the local
endpoint map.
binding_vec
Specifies a vector of binding handles over which the server can
receive remote procedure calls.
object_uuid_vec
Specifies a vector of object UUIDs that the server offers. The
server application constructs this vector.
Supply the value NULL to indicate there are no object UUIDs to
register.
annotation
Defines a character string comment applied to each cross-product
element added to the local endpoint map. The string can be up
to 64 characters long, including the NULL terminating character.
Specify NULL or the string \0 if there is no annotation string.
The string is used by applications for informational purposes
only. The RPC runtime does not use this string to determine which
server instance a client communicates with, or for enumerating
endpoint map elements.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
ept_s_cant_access
Error reading endpoint database.
ept_s_cant_create
Error creating endpoint database.
ept_s_cant_perform_op
Cannot perform requested operation.
ept_s_database_invalid
Endpoint map database invalid.
ept_s_invalid_entry
Invalid database entry.
ept_s_update_failed
Update failed.
rpc_s_comm_failure
Communications failure.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_no_bindings
No bindings.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_ep_register_no_replace() routine adds elements to the local
host's endpoint map. The routine does not replace existing elements.
Otherwise, this routine is identical to rpc_ep_register().
Each element in the local endpoint map logically contains the
following:
+ Interface ID, consisting of an interface UUID and versions
(major and minor)
+ Binding information
+ Object UUID (optional)
+ Annotation (optional)
A server uses this routine, instead of rpc_ep_register(), when
multiple instances of the server run on the same host. Use this
routine if, at any time, more than one server instance offers the
same interface UUID, object UUID, and protocol sequence.
Since this routine does not replace elements, calling servers must
unregister (that is, remove) themselves before they stop running.
Otherwise, when local endpoint map elements are not replaced,
obsolete elements accumulate each time a server instance stops running
without calling rpc_ep_unregister(). Periodically the DCE Host Daemon
identifies obsolete elements and removes them from the local endpoint
map. However, during the time between these removals, the obsolete
elements increase the chance that a client will receive endpoints to
nonexistent servers.The client then wastes time trying to communicate
with these servers before obtaining another endpoint.
A server program calls this routine to register endpoints that were
specified by calling any of the following routines:
+ rpc_server_use_all_protseqs()
+ rpc_server_use_protseq()
+ rpc_server_use_protseq_ep()
A server that calls only the rpc_server_use_all_protseqs_if() or
rpc_server_use_protseq_if() routine does not need to call this
routine. In such cases, the client's runtime uses an endpoint from
the client's interface specification to fill in a partially bound
binding handle. However, it is recommended that you also register
well-known endpoints that the server specifies (registering endpoints
from interface definitions is unnecessary).
If the server also exports to the name service database, the server
calls this routine with the same if_handle, binding_vec and
object_uuid_vec parameters as the server uses when calling the
rpc_ns_binding_export() routine.
The rpc_ep_register_no_replace() routine communicates with the DCE
Host Daemon (dced), which in turn communicates with the local
endpoint map. The routine communicates using one of the protocol
sequences specified in one of the binding handles in binding_vec.
Attempting to register a binding that specifies a protocol sequence
that the DCE Host daemon is not listening on results in the failure
of rpc_ep_register_no_replace(). The routine indicates this failure
by placing the value rpc_s_comm_failure into status.
For information about how the endpoint map service selects an element
for an interface ID and an object UUID, see the RPC information in the
OSF DCE Application Development Guide. This guide explains how the
endpoint map service searches for the endpoint of a server that is
compatible with a client. If the client supplies a non-nil object
UUID that is not in the endpoint map, or the client supplies a nil
object UUID, the search can succeed, but only if the server has
registered a nil object UUID using the rpc_ep_register_no_replace()
or rpc_ep_register() routine. The object_uuid_vec parameter can
contain both nil and non-nil object UUIDs for the routine to place
into endpoint map elements.
For an explanation of how a server can establish a client/server
relationship without using the local endpoint map, see the
explanation of a string binding in the rpc_intro reference page.
This routine creates a cross-product from the if_handle, binding_vec
and object_uuid_vec parameters, and adds each element in the cross-
product as a separate registration in the local endpoint map. If you
supply NULL to object_uuid_vec, the corresponding elements in the
cross-product contain a nil object UUID. The rpc_ep_register()
routine's reference page summarizes the contents of an element in
the local endpoint map.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_resolve_binding
rpc_ep_unregister
rpc_mgmt_ep_unregister
rpc_ns_binding_export
rpc_server_inq_bindings
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
Books: OSF DCE Application Development Guide.
3.33 – rpc_ep_resolve_binding
NAME
rpc_ep_resolve_binding - Resolves a partially bound server binding
handle into a fully bound server binding
handle
Used by client and management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ep_resolve_binding( rpc_binding_handle_t binding,
rpc_if_handle_t if_handle,
unsigned32 *status );
PARAMETERS
Input/Output
binding
Specifies a partially bound server binding handle to resolve
into a fully bound server binding handle.
if_handle
Contains a stub-generated data structure that specifies the
interface of interest.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
ept_s_not_registered
No entries found.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
rpc_s_rpcd_comm_failure
Communications failure while trying to reach the
endpoint map.
DESCRIPTION
An application calls the rpc_ep_resolve_binding() routine to resolve
a partially bound server binding handle into a fully bound server
binding handle.
Resolving binding handles requires an interface UUID and an object
UUID. The object UUID can be a nil UUID. The RPC runtime requests
the DCE Host Daemon's Endpoint Mapper Service, on the host that the
binding parameter specifies, to look up an endpoint for a compatible
server instance. The Endpoint Mapper Service finds the endpoint by
looking in the local endpoint map for the interface UUID from the
if_handle parameter and for the object UUID in the binding parameter.
The rpc_ep_resolve_binding() routine depends on whether the specified
binding handle is partially bound or fully bound. When the
application specifies a partially bound handle, the routine produces
the following results:
+ If no compatible server instances are registered in the local
endpoint map, the routine returns the ept_s_not_registered
status code.
+ If one compatible server instance is registered in the local
endpoint map, the routine returns a fully bound binding handle
in binding and the rpc_s_ok status code.
+ If more than one compatible server instance is registered in the
local endpoint map, the routine randomly selects one. It then
returns the corresponding fully bound binding handle in binding
and the rpc_s_ok status code.
When the application specifies a fully bound binding handle, the
routine returns the specified binding handle in binding and the
rpc_s_ok status code. The routine makes no request of the DCE Host
daemon.
In neither the partially bound case nor the fully bound case does the
routine contact a compatible server instance.
Using This Routine
For each server instance, the RPC runtime automatically provides
routines (the rpc_mgmt_* routines) that form an RPC management
interface. If a server instance registers any application-provided
interfaces, the RPC runtime automatically registers the RPC-provided
management interface with the local endpoint map for that server
instance.
An application can call rpc_ep_resolve_binding() at any time with
either a partially bound or a fully bound handle. However,
applications typically call this routine to avoid calling a routine
in the management interface with a partially bound handle.
An application can have a partially bound binding handle at the
following times:
+ After importing a binding handle.
+ After resetting a binding handle.
+ After converting a string binding without an endpoint to a
binding handle.
If an application calls an application-provided remote procedure using
a partially bound handle, the RPC runtime automatically asks the DCE
Host daemon to resolve the binding handle into a fully bound handle.
This fully bound binding handle corresponds to the RPC interface of
the called remote procedure and the requested object, if any. The
application can then use this fully bound handle to make remote
management calls, so calling the rpc_ep_resolve_binding() routine is
unnecessary.
When a high proportion of all servers in an environment offers the
same interface, the interface is known as a pervasive one. The RPC
management interface is a pervasive interface in all environments
that use DCE RPC.
Using this routine to unambiguously locate compatible server
instances applies to application-pervasive interfaces as well as
to the RPC management interface.
Partially Bound Handles with a Non-nil Object UUID
If the application has a partially bound handle with a non-nil
object UUID, the application can decide not to call the
rpc_ep_resolve_binding() routine before calling a procedure in the
management interface. In this case the remote management call is
sent to a server instance, registered on the remote host, that
offers that object UUID.
After completing the remote management call, the application has a
fully bound handle to that server instance. The server instance that
the handle specifies probably offers the non-management interfaces of
interest to the calling application. However, if you want to be
certain of obtaining a fully bound handle to a server instance that
offers the interfaces needed for later remote procedure calls, call
the rpc_ep_resolve_binding() routine.
Partially Bound Handles with a Nil Object UUID
When an application makes a remote procedure or management call using
a partially bound handle with a nil object UUID, the DCE Host daemon
searches for a compatible server instance. The search is based on
the nil object UUID and the UUID of the interface to which the call
belongs.
All server instances that register any RPC interface automatically
offer the RPC management interface. When an application makes a
remote management call using a partially bound handle with a nil
object UUID, the DCE Host daemon on the remote host cannot
distinguish among server instances registered in the local endpoint
map.
When the DCE Host daemon cannot distinguish among these instances it
selects any server instance. After completing the remote management
call, the calling application has a fully bound handle. However, the
server instance that the handle represents probably does not offer
the non-management interfaces that interest the application.
The remote RPC management routines avoid this ambiguity. They do
this by returning the status rpc_s_binding_incomplete if the
provided binding handle is a partially bound one with a nil object
UUID.
An application wanting to contact servers that have exported and
registered interfaces with a nil object UUID calls routine
rpc_ep_resolve_binding(). The application obtains a fully bound
binding handle for calling remote management procedures in a server
instance that also offers the remote procedures in the application-
specific interface.
Note that an application that wants to manage all the server instances
on a host does not call rpc_ep_resolve_binding(). Instead, the
application obtains fully bound binding handles for each server
instance by calling rpc_mgmt_ep_elt_inq_begin(),
rpc_mgmt_ep_elt_inq_next(), and rpc_mgmt_ep_elt_inq_done().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_register_no_replace
rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_done
rpc_mgmt_ep_elt_inq_next
rpc_binding_from_string_binding
rpc_binding_reset
3.34 – rpc_ep_unregister
NAME
rpc_ep_unregister - Removes server address information from the
local endpoint map
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ep_unregister( rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned32 *status );
PARAMETERS
Input
if_handle
Specifies an interface specification to remove (that is,
unregister) from the local endpoint map.
binding_vec
Specifies a vector of binding handles to remove.
object_uuid_vec
Specifies a vector of object UUIDs to remove. The server
application constructs this vector. This routine removes all
local endpoint map elements that match the specified if_handle
parameter, binding_vec parameter, and object UUIDs.
This is an optional parameter. The value NULL indicates there
are no object UUIDs to remove.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
ept_s_cant_access
Error reading endpoint database.
ept_s_cant_create
Error creating endpoint database.
ept_s_cant_perform_op
Cannot perform requested operation.
ept_s_database_invalid
Endpoint map database invalid.
ept_s_invalid_entry
Invalid database entry.
ept_s_update_failed
Update failed.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_no_bindings
No bindings.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_ep_unregister() routine removes elements from the local host's
endpoint map. A server application calls this routine only if the
server has registered endpoints previously and the server wishes to
remove that address information from the local endpoint map.
A server program is able to remove its own local endpoint map elements
(server address information) based on either of the following:
+ The interface specification.
+ The interface specification and the object UUIDs of resources
offered.
The server calls the rpc_server_inq_bindings() routine to obtain the
required binding_vec parameter. To remove selected endpoints, the
server can remove individual elements from binding_vec before calling
this routine. (See the explanation of a binding vector in the
rpc_intro reference page for more information about removing a single
element from a vector of binding handles.)
This routine creates a cross product from the if_handle, binding_vec
and object_uuid_vec parameters and removes each element in the cross
product from the local endpoint map. The rpc_ep_register() routine's
reference page summarizes the contents of a cross product in the local
endpoint map.
Servers must always call the rpc_ep_unregister() routine to remove
their endpoints from the local endpoint map before they exit.
Otherwise, stale information will be in the local endpoint map.
However, if a server prematurely removes endpoints (the server is
not in the process of exiting), clients that do not already have
fully bound binding handles to the server will not be able to send
remote procedure calls to the server.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_register_no_replace
rpc_mgmt_ep_unregister
rpc_ns_binding_unexport
rpc_server_inq_bindings
3.35 – rpc_if_id_vector_free
NAME
rpc_if_id_vector_free - Frees a vector and the interface identifier
structures it contains
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_if_id_vector_free( rpc_if_id_vector_t **if_id_vector,
unsigned32 *status );
PARAMETERS
Input/Output
if_id_vector
Specifies the address of a pointer to a vector of interface
information. On return the pointer is set to NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their explanations
are as follows:
rpc_s_ok Success.
rpc_s_invalid_arg
Invalid argument.
DESCRIPTION
The rpc_if_id_vector_free() routine frees the memory used to store
a vector of interface identifiers. This includes memory used by the
interface identifiers and the vector itself. On return this routine
sets the if_id_vector parameter to NULL.
To obtain a vector of interface identifiers, call
rpc_ns_mgmt_entry_inq_if_ids() or rpc_mgmt_inq_if_ids(). Call
rpc_if_id_vector_free() if you have used either of these routines.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_if_inq_id
rpc_mgmt_inq_if_ids
rpc_ns_mgmt_entry_inq_if_ids
3.36 – rpc_if_inq_id
NAME
rpc_if_inq_id - Returns the interface identifier for an interface
specification
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_if_inq_id( rpc_if_handle_t if_handle,
rpc_if_id_t *if_id,
unsigned32 *status );
PARAMETERS
Input
if_handle
Represents a stub-generated data structure that specifies the
interface specification to inquire about.
Output
if_id
Returns the interface identifier. The application provides
memory for the returned data.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status code and its meaning is as
follows:
rpc_s_ok
Success.
DESCRIPTION
An application calls the rpc_if_inq_id() routine to obtain a copy of
the interface identifier from the provided interface specification.
The returned interface identifier consists of the interface UUID and
interface version numbers (major and minor) specified in the DCE IDL
file's interface specification.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_if_id_vector_free
rpc_mgmt_inq_if_ids
rpc_ns_mgmt_entry_inq_if_ids
3.37 – rpc_mgmt_ep_elt_inq_begin
NAME
rpc_mgmt_ep_elt_inq_begin - Creates an inquiry context for viewing
the elements in an endpoint map
Used by management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_ep_elt_inq_begin( rpc_binding_handle_t ep_binding,
unsigned32 inquiry_type,
rpc_if_id_t *if_id,
unsigned32 vers_option,
uuid_t *object_uuid,
rpc_ep_inq_handle_t *inquiry_context,
unsigned32 *status );
PARAMETERS
Input
ep_binding
Specifies the host whose local endpoint map elements you receive.
To receive elements from the same host as the calling application,
specify NULL.
To receive local endpoint map elements from another host, specify
a server binding handle for that host. You can specify the same
binding handle you are using to make other remote procedure calls.
The object UUID associated with this parameter must be a nil UUID.
If you specify a non-nil UUID, the routine fails with the status
code ept_s_cant_perform_op. Other than the host information and
object UUID, all information in this parameter is ignored.
inquiry_type
Specifies an integer value that indicates the type of inquiry
to perform on the local endpoint map. The following list shows
the valid inquiry types:
Valid Inquiries on Local Endpoint Maps
_____________________________________________________________________
Value Description
_____________________________________________________________________
rpc_c_ep_all_elts Returns every element from the local
endpoint map. The if_id, vers_option,
and object_uuid parameters are ignored.
rpc_c_ep_match_by_if Searches the local endpoint map for
those elements that contain the inter-
face identifier specified by the if_id
and vers_option values. The object_uuid
parameter is ignored.
rpc_c_ep_match_by_obj Searches the local endpoint map for
those elements that contain the object
UUID specified by the object_uuid param-
eter. The if_id and vers_option parame-
ters are ignored.
rpc_c_ep_match_by_both Searches the local endpoint map for
those elements that contain the inter-
face identifier and object UUID speci-
fied by the if_id, vers_option, and
object_uuid parameters.
Specifies the interface identifier of the local endpoint map
elements to be returned by the rpc_mgmt_ep_elt_inq_next() routine.
Use this parameter only when specifying a value of
rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the
inquiry_type parameter. Otherwise, this parameter is ignored
and the value NULL can be specified.
Specifies how the rpc_mgmt_ep_elt_inq_next() routine uses the
if_id parameter. Use this parameter only when specifying a
value of rpc_c_ep_match_by_if or rpc_c_ep_match_by_both for the
inquiry_type parameter. Otherwise, this parameter is ignored
and a 0 (zero) value can be specified.
The following list presents the valid values for this parameter:
Valid values of vers_option
_____________________________________________________________________
Value Description
_____________________________________________________________________
rpc_c_vers_all Returns local endpoint map elements that
offer the specified interface UUID,
regardless of the version numbers. For
this value, specify 0 (zero) for both
the major and minor versions in if_id.
rpc_c_vers_compatible Returns local endpoint map elements that
offer the same major version of the
specified interface UUID and a minor
version greater than or equal to the
minor version of the specified interface
UUID.
rpc_c_vers_exact Returns local endpoint map elements that
offer the specified version of the
specified interface UUID.
rpc_c_vers_major_only Returns local endpoint map elements that
offer the same major version of the
specified interface UUID (ignores the
minor version). For this value, specify
0 (zero) for the minor version in if_id.
rpc_c_vers_upto Returns local endpoint map elements that
offer a version of the specified inter-
face UUID less than or equal to the
specified major and minor version. (For
example, suppose if_id contains V2.0 and
the local endpoint map contained ele-
ments with the following versions: V1.3,
V2.0, and V2.1. The
rpc_mgmt_ep_elt_inq_next routine returns
the elements with V1.3 and V2.0.)
Specifies the object UUID that rpc_mgmt_ep_elt_inq_next() looks
for in local endpoint map elements.
This parameter is used only when you specify a value of
rpc_c_ep_match_by_obj or rpc_c_ep_match_by_both for the
inquiry_type parameter. Otherwise, this parameter is ignored
and you can supply NULL to specify a nil UUID.
Output
inquiry_context
Returns an inquiry context for use with the
rpc_mgmt_ep_elt_inq_next() and rpc_mgmt_ep_elt_inq_done()
routines.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings are
as follows:
rpc_s_ok Success.
rpc_s_invalid_inquiry_context
Invalid inquiry context.
rpc_s_invalid_inquiry_type
Invalid inquiry type.
rpc_s_invalid_vers_option
Invalid version option.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_mgmt_ep_elt_inq_begin() routine creates an inquiry context for
viewing server address information stored in the local endpoint map.
Using the inquiry_type and vers_option parameters, an application
specifies which of the following local endpoint map elements are
returned from calls to the rpc_mgmt_ep_elt_inq_next() routine:
+ All elements.
+ Those elements with the specified interface identifier.
+ Those elements with the specified object UUID.
+ Those elements with both the specified interface identifier and
object UUID.
Before calling the rpc_mgmt_ep_elt_inq_next() routine, the application
must first call this routine to create an inquiry context.
After viewing the local endpoint map elements, the application calls
the rpc_mgmt_ep_elt_inq_done() routine to delete the inquiry context.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_register_no_replace
rpc_ep_unregister
rpc_mgmt_ep_elt_inq_done
rpc_mgmt_ep_elt_inq_next
rpc_mgmt_ep_unregister
3.38 – rpc_mgmt_ep_elt_inq_done
NAME
rpc_mgmt_ep_elt_inq_done - Deletes the inquiry context for viewing
the elements in an endpoint map
Used by management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_ep_elt_inq_done( rpc_ep_inq_handle_t *inquiry_context,
unsigned32 *status );
PARAMETERS
Input/Output
inquiry_context
Specifies the inquiry context to delete. (An inquiry context is
created by calling rpc_mgmt_ep_elt_inq_begin().)
Returns the value NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_inquiry_context
Invalid inquiry context.
DESCRIPTION
The rpc_mgmt_ep_elt_inq_done() routine deletes an inquiry context.
The rpc_mgmt_ep_elt_inq_begin() routine created the inquiry context.
An application calls this routine after viewing local endpoint map
elements using the rpc_mgmt_ep_elt_inq_next() routine.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_next
3.39 – rpc_mgmt_ep_elt_inq_next
NAME
rpc_mgmt_ep_elt_inq_next - Returns one element from an endpoint map
Used by management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_ep_elt_inq_next( rpc_ep_inq_handle_t inquiry_context,
rpc_if_id_t *if_id,
rpc_binding_handle_t *binding,
uuid_t *object_uuid,
unsigned_char_t **annotation,
unsigned32 *status );
PARAMETERS
Input
inquiry_context
Specifies an inquiry context. This inquiry context is returned
from the rpc_mgmt_ep_elt_inq_begin() routine.
Output
if_id
Returns the interface identifier of the local endpoint map
element.
binding
Returns the binding handle from the local endpoint map element.
Specify NULL to prevent the routine from returning this parameter.
In this case the application does not call the rpc_binding_free()
routine.
object_uuid
Returns the object UUID from the local endpoint map element.
Specify NULL to prevent the routine from returning this parameter.
annotation
Returns the annotation string for the local endpoint map element.
If there is no annotation string in the local endpoint map
element, the string \0 is returned.
Specify NULL to prevent the routine from returning this argument.
In this case the application does not call the rpc_string_free()
routine.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
ept_s_cant_perform_op
Cannot perform the requested operation.
rpc_s_comm_failure
Communications failure.
ept_s_database_invalid
Endpoint map database invalid.
rpc_s_fault_context_mismatch
Fault context mismatch.
ept_s_invalid_context
Invalid inquiry type for this context.
ept_s_invalid_entry
Invalid database entry.
rpc_s_invalid_arg
Invalid argument.
rpc_s_invalid_inquiry_context
Invalid inquiry context.
rpc_s_invalid_inquiry_type
Invalid inquiry type.
rpc_s_no_more_elements
No more elements.
DESCRIPTION
The rpc_mgmt_ep_elt_inq_next() routine returns one element from the
local endpoint map. Regardless of the selector value specified for
the inquiry_type parameter in rpc_mgmt_ep_elt_inq_begin(), this
routine returns all the components of a selected local endpoint map
element. The rpc_ep_register() routine's reference page summarizes
the contents of an element in the local endpoint map.
An application can view all the selected local endpoint map elements
by repeatedly calling the rpc_mgmt_ep_elt_inq_next() routine. When
all the elements have been viewed, this routine returns an
rpc_s_no_more_elements status. The returned elements are unordered.
If a remote endpoint map contains elements that include a protocol
sequence that your system does not support, this routine does not
return the elements. (A protocol sequence is part of the binding
information component of an endpoint map element.) To receive all
possible elements from a remote endpoint map, your application must
run on a system that supports the protocol sequences included in
the elements.
For example, if your system does not support protocol sequence
ncacn_ip_tcp and a remote endpoint map contains elements that
include this protocol sequence, this routine does not return these
elements to your application. If your application ran on a system
that supported protocol sequence ncacn_ip_tcp, this routine would
return the elements.
The RPC runtime allocates memory for the returned binding and the
annotation string on each call to this routine. The application
calls the rpc_binding_free() routine for each returned binding and
the rpc_string_free() routine for each returned annotation string.
After viewing the local endpoint map's elements, the application must
call the rpc_mgmt_ep_elt_inq_done() routine to delete the inquiry
context.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_mgmt_ep_elt_begin
rpc_mgmt_ep_elt_done
rpc_string_free
3.40 – rpc_mgmt_ep_unregister
NAME
rpc_mgmt_ep_unregister - Removes server address information from
an endpoint map
Used by management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_ep_unregister( rpc_binding_handle_t ep_binding,
rpc_if_id_t *if_id,
rpc_binding_handle_t binding,
uuid_t *object_uuid,
unsigned32 *status );
PARAMETERS
Input
ep_binding
Specifies the host whose local endpoint map elements you
unregister (that is, remove). To remove elements from the same
host as the calling application, specify NULL.
To remove local endpoint map elements from another host, specify
a server binding handle for that host. You can specify the same
binding handle you are using to make other remote procedure calls.
The object UUID associated with this parameter must be a nil UUID.
If you specify a non-nil UUID, the routine fails with the status
code ept_s_cant_perform_op. Other than the host information and
object UUID, all information in this parameter is ignored.
if_id
Specifies the interface identifier to remove from the local
endpoint map.
binding
Specifies the binding handle to remove.
object_uuid
Specifies an optional object UUID to remove.
The value NULL indicates there is no object UUID to consider in
the removal.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
ept_s_cant_access
Error reading the endpoint database.
ept_s_cant_perform_op
Cannot perform the requested operation.
rpc_s_comm_failure
Communications failure.
ept_s_database_invalid
Endpoint map database is invalid.
ept_s_invalid_entry
Invalid database entry.
ept_s_not_registered
No entries found.
ept_s_update_failed
Update failed.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_no_interfaces
No interfaces registered.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_mgmt_ep_unregister() routine unregisters (that is, removes)
an element from a local endpoint map. A management program calls
this routine to remove addresses of servers that are no longer
available, or to remove addresses of servers that support objects
that are no longer offered.
Use this routine cautiously; removing elements from the local endpoint
map may make servers unavailable to client applications that do not
already have a fully bound binding handle to the server.
A management application calls the rpc_mgmt_ep_inq_next() routine to
view local endpoint map elements. The application can then remove
the elements using the rpc_mgmt_ep_unregister() routine.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_unexport
rpc_mgmt_ep_elt_inq_begin
rpc_mgmt_ep_elt_inq_done
rpc_mgmt_ep_elt_inq_next
3.41 – rpc_mgmt_inq_com_timeout
NAME
rpc_mgmt_inq_com_timeout - Returns the communications time-out value
in a binding handle
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_inq_com_timeout( rpc_binding_handle_t binding,
unsigned32 *timeout,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a server binding handle.
Output
timeout
Returns the communications time-out value from the binding
parameter.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_mgmt_inq_com_timeout() routine returns the communications
timeout value in a server binding handle. The time-out value
specifies the relative amount of time to spend trying to communicate
with the server. Depending on the protocol sequence for the
specified binding handle, the value in timeout acts only as advice
to the RPC runtime.
The rpc_mgmt_set_com_timeout reference page explains the time-out
values returned in timeout.
To change the timeout value, a client calls
rpc_mgmt_set_com_timeout().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_mgmt_set_com_timeout
3.42 – rpc_mgmt_inq_dflt_protect_level
NAME
rpc_mgmt_inq_dflt_protect_level - Returns the default protection level
for an authentication service
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_inq_dflt_protect_level( unsigned32 authn_svc,
unsigned32 *protect_level,
unsigned32 *status );
PARAMETERS
Input
authn_svc
Specifies the authentication service for which to return the
default protection level.
The supported authentication services are as follows:
rpc_c_authn_none
No authentication.
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
rpc_c_authn_default
DCE default authentication service.
Output
protect_level
Returns the default protection level for the specified
authentication service. The protection level determines the
degree to which authenticated communications between the client
and the server are protected. The possible protection levels
are as follows:
rpc_c_protect_level_default
Uses the default protection level for the specified
authentication service.
rpc_c_protect_level_none
Performs no protection.
rpc_c_protect_level_connect
Performs protection only when the client establishes
a relationship with the server.
rpc_c_protect_level_call
Performs protection only at the beginning of each
remote procedure call when the server receives the
request.
rpc_c_protect_level_pkt
Ensures that all data received is from the expected
client.
rpc_c_protect_level_pkt_integ
Ensures and verifies that none of the data
transferred between client and server has been
modified.
rpc_c_protect_level_pkt_privacy
Performs protection as specified by all of the
previous levels and also encrypts each remote
procedure call argument value.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_unknown_authn_service
Unknown authentication service.
DESCRIPTION
The rpc_mgmt_inq_dflt_protect_level() routine returns the default
protection level for the specified authentication service.
A client can call this routine to learn the default protection level
before specifying rpc_c_protect_level_default for the protect_level
parameter in the rpc_binding_set_auth_info() routine. If the default
level is inappropriate, the client can specify a different, explicit
level.
A called remote procedure within a server application can call
this routine to obtain the default protection level for a given
authentication service. By calling routine
rpc_binding_inq_auth_client() in the remote procedure, the server
can obtain the protection level set up by the calling client. The
server can then compare the client-specified protection level with
the default level to determine whether to allow the remote procedure
to execute.
Alternatively, a remote procedure can compare the client's protection
level against a level other than the default level. In this case
there is no need for the server's remote procedure to call this
routine.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_inq_auth_client
rpc_binding_set_auth_info
3.43 – rpc_mgmt_inq_if_ids
NAME
rpc_mgmt_inq_if_ids - Returns a vector of interface identifiers of
interfaces a server offers
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_inq_if_ids( rpc_binding_handle_t binding,
rpc_if_id_vector_t **if_id_vector,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a binding handle. To receive interface identifiers
from a remote application, specify a server binding handle for
that application. To receive interface information about your
own (local) application, specify NULL.
If the binding handle you supply refers to partially bound binding
information and the binding information contains a nil object
UUID, this routine returns the rpc_s_binding_incomplete status
code. In this case, the DCE Host Daemon (dced) does not know which
serveR instance to select from the local endpoint map because the
RPC management interface is automatically registered (by the RPC
runtime) for all RPC servers. To avoid this situation, you can
obtain a fully bound server binding handle by calling the
rpc_ep_resolve_binding() routine.
Output
if_id_vector
Returns the address of an interface identifier vector.
status
Returns the status code from this routine, which indicates
whether the routine completed successfully or, if not, why
not. The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_binding_incomplete
Binding incomplete (no object ID and no endpoint).
rpc_s_comm_failure
Communications failure.
rpc_s_invalid_arg
Invalid argument.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_mgmt_op_disallowed
Management operation disallowed.
rpc_s_no_interfaces
No interfaces registered.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
In addition to the values above, status can return the value of
parameter status from the application-defined authorization function
(rpc_mgmt_authorization_fn_t). The prototype for such a function is
defined in the authorization_fn parameter listed in the reference page
for the rpc_mgmt_set_authorization_fn routine.
DESCRIPTION
An application calls the rpc_mgmt_inq_if_ids() routine to obtain a
vector of interface identifiers listing the interfaces registered by
a server with the RPC runtime.
If a server has not registered any interfaces with the runtime, this
routine returns a rpc_s_no_interfaces status code and an if_id_vector
parameter value of NULL.
The application calls the rpc_if_id_vector_free() routine to release
the memory used by the vector.
By default, the RPC runtime allows all clients to remotely call
this routine. To restrict remote calls of this routine, a server
application supplies an authorization function using the
rpc_mgmt_set_authorization_fn() routine.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_resolve_binding
rpc_if_id_vector_free
rpc_mgmt_set_authorization_fn
rpc_server_register_if
3.44 – rpc_mgmt_inq_server_princ_name
NAME
rpc_mgmt_inq_server_princ_name - Returns a server's principal name
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_inq_server_princ_name(
rpc_binding_handle_t binding,
unsigned32 authn_svc,
unsigned_char_t **server_princ_name,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a binding handle. If a client application wants the
princi pal name from a server application, supply a server
binding handle for that server. For a server application to
receive a principal name of itself, supply the value NULL.
If the binding handle you supply refers to partially bound
binding information and the binding information contains a nil
object UUID, this routine returns the rpc_s_binding_incomplete
status code. In this case the DCE Host Daemon does not know
which server instance to select from the local endpoint map
because the RPC runtime automatically registers the RPC
management interface for all RPC servers. You can avoid this
situation by calling rpc_ep_resolve_binding() to obtain a fully
bound server binding handle.
authn_svc
Specifies the authentication service for which a principal name
is returned. The rpc_binding_set_auth_info reference page, in
its explanation of the authn_svc parameter, contains a list of
supported authentication services.
Output
server_princ_name
Returns a principal name. This name is registered for the
authentication service in parameter authn_svc by the server
referenced in parameter binding. If the server registered
multiple principal names, only one of them is returned.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_binding_incomplete
Binding incomplete (no object ID and no endpoint).
rpc_s_comm_failure
Communications failure.
rpc_s_mgmt_op_disallowed
Management operation disallowed.
rpc_s_unknown_authn_service
Unknown authentication service.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
In addition to the above values, status can return the value of
parameter status from the application-defined authorization function
(rpc_mgmt_authorization_fn_t). The prototype for such a function is
defined in the authorization_fn parameter in the reference page for
rpc_mgmt_set_authorization_fn.
DESCRIPTION
An application calls the rpc_mgmt_inq_server_princ_name() routine to
obtain the principal name of a server registered for a specified
authentication service.
A client (or management) application uses this routine when it wants
to allow one-way authentication with the server specified by binding.
This means that the client does not care which server principal
receives the remote procedure call request. However, the server
verifies that the client is who the client claims to be. For one-way
authentication, a client calls this routine before calling
rpc_binding_set_auth_info().
A server application uses this routine to obtain the principal name
it registered by calling rpc_server_register_auth_info().
The RPC runtime allocates memory for the string returned in
server_princ_name. The application calls rpc_string_free() to
deallocate that memory.
By default, the RPC runtime allows all clients to call this routine
remotely. To restrict these calls, a server application supplies an
authorization function by calling rpc_mgmt_set_authorization_fn().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_inq_object
rpc_binding_set_auth_info
rpc_ep_resolve_binding
rpc_mgmt_set_authorization_fn
rpc_server_register_auth_info
rpc_string_free
uuid_is_nil
3.45 – rpc_mgmt_inq_stats
NAME
rpc_mgmt_inq_stats - Returns RPC runtime statistics
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_inq_stats( rpc_binding_handle_t binding,
rpc_stats_vector_t **statistics,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a binding handle. To receive statistics about a remote
application, specify a server binding handle for that application.
To receive statistics about your own (local) application, specify
NULL. If the binding handle you supply refers to partially bound
binding information and the binding information contains a nil
object UUID, this routine returns the rpc_s_binding_incomplete
status code. In this case, the DCE Host Daemon does not know
which server instance to select from the local endpoint map
because the RPC management interface is automatically registered
(by the RPC runtime) for all RPC servers. To avoid this
situation, you can obtain a fully bound server binding handle by
calling the rpc_ep_resolve_binding() routine.
Output
statistics
Returns the statistics vector for the server specified by the
binding parameter. Each statistic is a value of the type
unsigned32.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_binding_incomplete
Binding incomplete (no object ID and no endpoint).
rpc_s_comm_failure
Communications failure.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_mgmt_op_disallowed
Management operation disallowed.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
In addition to the above values, status can return the value of
parameter status from the application-defined authorization function
rpc_mgmt_authorization_fn_t(). The prototype for such a function is
defined in the authorization_fn parameter in the reference page for
rpc_mgmt_set_authorization_fn.
DESCRIPTION
The rpc_mgmt_inq_stats() routine returns statistics from the RPC
runtime about a specified server.
The explanation of a statistics vector in the rpc_intro reference
page lists the elements of the vector.
The RPC runtime allocates memory for the statistics vector. The
application calls the rpc_mgmt_stats_vector_free() routine to
release the memory that the statistics vector used.
By default, the RPC runtime allows all clients to remotely call
this routine. To restrict remote calls of this routine, a server
application supplies an authorization function using the
rpc_mgmt_set_authorization_fn() routine.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_resolve_binding
rpc_mgmt_set_authorization_fn
rpc_mgmt_stats_vector_free
3.46 – rpc_mgmt_is_server_listening
NAME
rpc_mgmt_is_server_listening - Tells whether a server is listening
for remote procedure calls
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
boolean32 rpc_mgmt_is_server_listening( rpc_binding_handle_t binding,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a server binding handle. To determine if a remote
application is listening for remote procedure calls, specify a
server binding handle for that application. To determine if
your own (local) application is listening for remote procedure
calls, specify NULL.
If the binding handle you supply refers to partially bound binding
information and the binding information contains a nil object
UUID,this routine returns the rpc_s_binding_incomplete status
code. In this case, the DCE Host Daemon does not know which server
instance to select from the local endpoint map because the RPC
management interface is automatically registered (by the RPC
runtime) for all RPC servers. To avoid this situation, you can
obtain a fully bound server binding handle by calling the
rpc_ep_resolve_binding() routine.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings are
as follows:
rpc_s_ok Success.
rpc_s_binding_incomplete
Binding incomplete (no object ID and no endpoint).
rpc_s_comm_failure
Communications failure.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_mgmt_op_disallowed
Management operation disallowed.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
In addition to the above values, status can return the value of
parameter status from the application-defined authorization function
(rpc_mgmt_authorization_fn_t). The prototype for such a function is
defined in the authorization_fn parameter in the reference page for
rpc_mgmt_set_authorization_fn.
DESCRIPTION
The rpc_mgmt_is_server_listening() routine determines whether the
server specified in the binding parameter is listening for remote
procedure calls.
This routine returns a value of TRUE if the server is blocked in the
rpc_server_listen() routine.
By default, the RPC runtime allows all clients to remotely call
this routine. To restrict remote calls of this routine, a server
application supplies an authorization function using the
rpc_mgmt_set_authorization_fn() routine.
RETURN VALUES
Your program must examine the return value of the status parameter
and the return value of the routine to understand the meaning of the
routine value. The following table summarizes the values that this
routine can return.
Values Returned by rpc_mgmt_is_server_listening()
_____________________________________________________________________
Value Returned Status Code Explanation
_____________________________________________________________________
TRUE rpc_s_ok The specified server is
listening for remote
procedure calls.
FALSE One of the status The specified server is
codes listed for not listening for remote
the status parameter procedure calls, or the
server cannot be reached.
RELATED INFORMATION
Functions: rpc_ep_resolve_binding
rpc_mgmt_set_authorization_fn
rpc_server_listen
3.47 – rpc_mgmt_set_authorization_fn
NAME
rpc_mgmt_set_authorization_fn - Establishes an authorization function
for processing remote calls to a
server's management routines
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_set_authorization_fn(
rpc_mgmt_authorization_fn_t authorization_fn,
unsigned32 *status );
PARAMETERS
Input
authorization_fn
Specifies a pointer to an authorization function. The RPC server
runtime automatically calls this function whenever the server
runtime receives a client request to execute one of the RPC
management routines.
Specify NULL to unregister a previously registered authorization
function. In this case, the default authorizations (as described
later) are used.
The following C definition for rpc_mgmt_authorization_fn_t
illustrates the prototype for the authorization function:
typedef boolean32 (*rpc_mgmt_authorization_fn_t)
(
rpc_binding_handle_t client_binding, /* in */
unsigned32 requested_mgmt_operation, /* in */
unsigned32 *status /* out */
);
The following table shows the requested_mgmt_operation Values
passed by the RPC runtime to the authorization function.
Operation Values Passed to Authorization Function
_________________________________________________________________
Called Remote Routine requested_mgmt_operation Value
_________________________________________________________________
rpc_mgmt_inq_if_ids() rpc_c_mgmt_inq_if_ids
rpc_mgmt_inq_server_princ_name() rpc_c_mgmt_inq_princ_name
rpc_mgmt_inq_stats() rpc_c_mgmt_inq_stats
rpc_mgmt_is_server_listening() rpc_c_mgmt_is_server_listen
rpc_mgmt_stop_server_listening() rpc_c_mgmt_stop_server_listen
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status code and its meaning is as
follows:
rpc_s_ok
Success.
DESCRIPTION
The rpc_mgmt_set_authorization_fn() routine sets up an authorization
function to control remote access to the calling server's remote
management routines.
If a server does not provide an authorization function, the RPC
runtime controls client application access to the server's remote
management routines as shown in the next table. In the table, an
Enabled authorization allows all clients to execute the remote
routine and a Disabled authorization prevents all clients from
executing the remote routine.
Default Controls for Remote Management Routines
________________________________________________________
Remote Routine Default Authorization
________________________________________________________
rpc_mgmt_inq_if_ids() Enabled
rpc_mgmt_inq_server_princ_name() Enabled
rpc_mgmt_inq_stats() Enabled
rpc_mgmt_is_server_listening() Enabled
rpc_mgmt_stop_server_listening() Disabled
A server can modify the default authorizations by calling
rpc_mgmt_set_authorization_fn() to specify an authorization
function. When an authorization function is provided, the RPC
runtime automatically calls that function to control the execution
of all remote management routines called by clients.
The specified function must provide access control for all of the
remote management routines.
If the authorization function returns TRUE, the management routine
is allowed to execute. If the authorization function returns FALSE,
the management routine does not execute, and the called routine
returns to the client the status code returned from the
rpc_mgmt_authorization_fn_t function. However, if the status code
that the rpc_mgmt_authorization_fn_t function returns is 0 (zero) or
rpc_s_ok, then the status code rpc_s_mgmt_op_disallowed is returned
to the client.
The RPC runtime calls the server-provided authorization function with
the following two input arguments:
+ The binding handle of the calling client.
+ An integer value denoting which management routine the client has
called.
Using these arguments, the authorization function determines whether
the calling client is allowed to execute the requested management
routine. For example, the authorization function can call
rpc_binding_inq_auth_client() to obtain authentication and
authorization information about the calling client and determine if
that client is authorized to execute the requested management routine.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_mgmt_ep_unregister
rpc_mgmt_inq_if_ids
rpc_mgmt_inq_server_princ_name
rpc_mgmt_inq_stats
rpc_mgmt_is_server_listening
rpc_mgmt_stop_server_listening
3.48 – rpc_mgmt_set_cancel_timeout
NAME
rpc_mgmt_set_cancel_timeout - Sets the lower bound on the time to
wait before timing out after
forwarding a cancel
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_set_cancel_timeout( signed32 seconds,
unsigned32 *status );
PARAMETERS
Input
seconds
An integer specifying the number of seconds to wait for a
server to acknowledge a cancel. To specify that a client
waits an infinite amount of time, supply the value
rpc_c_cancel_infinite_timeout.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status code and its meaning is as
follows:
rpc_s_ok
Success.
DESCRIPTION
The rpc_mgmt_set_cancel_timeout() routine resets the amount of time
the RPC runtime waits for a server to acknowledge a cancel before
orphaning the call.
The application specifies either to wait forever or to wait a length
of time specified in seconds. If the value of seconds is 0 (zero), the
remote procedure call is immediately orphaned when the RPC runtime
detects and forwards a pending cancel; control returns immediately to
the client application. The default value,
rpc_c_cancel_infinite_timeout, specifies waiting forever for the call
to complete.
The value for the cancel time-out applies to all remote procedure
calls made in the current thread. A multithreaded client that wishes
to change the time-out value must call this routine in each thread
of execution.
For more information about canceled threads and orphaned remote
procedure calls, see the OSF DCE Application Development Guide.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: pthread_cancel
pthread_setcancel
Books: OSF DCE Application Development Guide.
3.49 – rpc_mgmt_set_com_timeout
NAME
rpc_mgmt_set_com_timeout - Sets the communications time-out value
in a binding handle
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_set_com_timeout( rpc_binding_handle_t binding,
unsigned32 timeout,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies the server binding handle whose time-out value is set.
timeout
Specifies a communications time-out value.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_invalid_timeout
Invalid time-out value.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_mgmt_set_com_timeout() routine resets the communications
time-out value in a server binding handle. The time-out value
specifies the relative amount of time to spend trying to communicate
with the server. Depending on the protocol sequence for the
specified binding handle, the timeout value acts only as advice to
the RPC runtime.
After the initial relationship is established, subsequent
communications for the binding handle can revert to not less than
the default time-outs for the protocol service. This means that after
setting a short initial time-out, establishing a connection, calls in
progress are not timed out any sooner than the default.
The time-out value can be any integer value from 0 (zero) to 10. Note
that these values do not represent seconds. They represent a relative
amount of time to spend to establish a client/server relationship
(a binding).
Constants are provided for certain values in the time-out range. The
following table lists the binding time-out values, describing the DCE
RPC predefined values that an application can use for the timeout
parameter.
Predefined Time-Out Values
_____________________________________________________________________
Name Value Description
_____________________________________________________________________
rpc_c_binding_min_timeout 0 Attempts to communicate for the
minimum amount of time for the
network protocol being used.
This value favors response time
over correctness in determining
whether the server is running.
rpc_c_binding_default_timeout 5 Attempts to communicate for an
average amount of time for the
network protocol being used.
This value gives equal con-
sideration to response time and
correctness in determining
whether a server is running.
This is the default value.
rpc_c_binding_max_timeout 9 Attempts to communicate for the
longest finite amount of time
for the network protocol being
used. This value favors
correctness in determining
whether a server is running
over response time.
rpc_c_binding_infinite_timeout 10 Attempts to communicate
forever.
Note that connection-oriented RPC handles the time-out value
differently from Datagram RPC. Because connection-oriented RPC is
based upon a reliable transport layer, communications time-outs are
not as significant as they are under datagram protocol. When
rpc_mgmt_set_com_timeout() is called on a binding using connection-
oriented protocol, only the input argument
rpc_c_binding_infinite_timeout changes the binding's behavior.
All other values are ignored.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_mgmt_inq_com_timeout
3.50 – rpc_mgmt_set_server_stack_size
NAME
rpc_mgmt_set_server_stack_size - Specifies the stack size for each
server thread
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_set_server_stack_size( unsigned32 thread_stack_size,
unsigned32 *status );
PARAMETERS
Input
thread_stack_size
Specifies, in bytes, the stack size allocated for each thread
created by rpc_server_listen(). This value is applied to all
threads created for the server. Select this value based on the
stack requirements of the remote procedures offered by the server.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_arg
Invalid argument.
rpc_s_not_supported
Not supported.
DESCRIPTION
The rpc_mgmt_set_server_stack_size() routine specifies the thread
stack size to use when the RPC runtime creates call threads for
executing remote procedure calls. The max_calls_exec parameter in
rpc_server_listen() specifies the number of call execution threads
created.
A server, provided it knows the stack requirements of all the manager
routines in the interfaces it offers, can call
rpc_mgmt_set_server_stack_size() to ensure that each call thread has
the necessary stack size.
This routine is optional. When it is used, it must be called before
the server calls rpc_server_listen(). If a server does not call this
routine, the default per thread stack size from the underlying threads
package is used.
Some thread packages do not support the specification or modification
of thread stack sizes. The packages cannot perform such operations or
the concept of a thread stack size is meaningless to them.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_server_listen
3.51 – rpc_mgmt_stats_vector_free
NAME
rpc_mgmt_stats_vector_free - Frees a statistics vector
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_mgmt_stats_vector_free( rpc_stats_vector_t **stats_vector,
unsigned32 *status );
PARAMETERS
Input/Output
stats_vector
Specifies the address of a pointer to a statistics vector.
On return, stats_vector contains the value NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status code and its meaning is as
follows:
rpc_s_ok
Success.
DESCRIPTION
An application calls rpc_mgmt_stats_vector_free() to release the
memory used to store a vector of statistics.
An application calls rpc_mgmt_inq_stats() to obtain a vector of
statistics. Follow a call to rpc_mgmt_inq_stats() with a call to
rpc_mgmt_stats_vector_free().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_mgmt_inq_stats
3.52 – rpc_mgmt_stop_server_listening
NAME
rpc_mgmt_stop_server_listening - Tells a server to stop listening
for remote procedure calls
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>(
void rpc_mgmt_stop_server_listening( rpc_binding_handle_t binding,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a server binding handle. To direct a remote server to
stop listening for remote procedure calls, specify a server
binding handle to that server. To direct your own (local) server
to stop listening for remote procedure calls, specify NULL.
If the binding handle you supply refers to partially bound binding
information and the binding information contains a nil object
UUID, this routine returns the rpc_s_binding_incomplete status
code. In this case, the DCE Host Daemon does not know which server
instance to select from the local endpoint map because the RPC
management interface is automatically registered (by the RPC
runtime) for all RPC servers. To avoid this situation, you can
obtain a fully bound server binding handle by calling
rpc_ep_resolve_binding().
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_binding_incomplete
Binding incomplete (no object ID and no endpoint).
rpc_s_comm_failure
Communications failure.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_mgmt_op_disallowed
Management operation disallowed.
rpc_s_unknown_if
Unknown interface.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
In addition to the above values, status can return the value of
parameter status from the application-defined authorization function
rpc_mgmt_authorization_fn_t(). The prototype for such a function is
defined in the authorization_fn parameter in the reference page for
rpc_mgmt_set_authorization_fn.
DESCRIPTION
The rpc_mgmt_stop_server_listening() routine directs a server to stop
listening for remote procedure calls.
On receiving such a request, the DCE RPC runtime stops accepting new
remote procedure calls. Executing calls are allowed to complete.
After all calls complete, rpc_server_listen() returns to the caller.
By default, the RPC runtime does not allow any client to remotely
call this routine. To allow clients to execute this routine, a
server application supplies an authorization function using
rpc_mgmt_set_authorization_fn().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_resolve_binding
rpc_mgmt_set_authorization_fn
rpc_server_listen
3.53 – rpc_network_inq_protseqs
NAME
rpc_network_inq_protseqs - Returns all protocol sequences supported
by both the RPC runtime and the operating
system
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>(
void rpc_network_inq_protseqs( rpc_protseq_vector_t **protseq_vector,
unsigned32 *status );
PARAMETERS
Input
None.
Output
protseq_vector
Returns the address of a protocol sequence vector.
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_no_protseqs No supported protocol sequences.
DESCRIPTION
The rpc_network_inq_protseqs() routine obtains a vector containing
the protocol sequences supported by the RPC runtime and the operating
system. A server chooses to accept remote procedure calls over some
or all of the supported protocol sequences. If there are no supported
protocol sequences, this routine returns the rpc_s_no_protseqs status
code and the value NULL in the protseq_vector parameter.
The application calls rpc_protseq_vector_free() to release the memory
used by the vector.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_network_is_protseq_valid
rpc_protseq_vector_free
3.54 – rpc_network_is_protseq_valid
NAME
rpc_network_is_protseq_valid - Tells whether the specified protocol
sequence is supported by both the RPC
runtime and the operating system
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>(
boolean32 rpc_network_is_protseq_valid( unsigned_char_t *protseq,
unsigned32 *status );
PARAMETERS
Input
protseq
Specifies a string identifier for a protocol sequence. (See the
table of valid protocol sequences in the rpc_intro reference page
for a list of acceptable values.)
The rpc_network_is_protseq_valid() routine determines whether this
parameter contains a valid protocol sequence. If not, the routine
returns FALSE and the status parameter contains the
rpc_s_invalid_rpc_protseq status code.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_rpc_protseq
Invalid protocol sequence.
rpc_s_protseq_not_supported
Protocol sequence not supported on this host.
DESCRIPTION
The rpc_network_is_protseq_valid() routine determines whether a
specified protocol sequence is available for making remote procedure
calls. A server chooses to accept remote procedure calls over some
or all of the supported protocol sequences.
A protocol sequence is valid if the RPC runtime and the operating
system support the protocol sequence. DCE RPC supports the protocol
sequences pointed to by the explanation of the protseq parameter.
An application calls rpc_network_inq_protseqs() to obtain all the
supported protocol sequences.
RETURN VALUES
This routine can return the following values:
TRUE The RPC runtime supports the protocol sequence specified in
the protseq parameter. The routine returns the status code
rpc_s_ok in the status parameter.
FALSE The RPC runtime does not support the protocol sequence
specified in the protseq parameter.
RELATED INFORMATION
Functions: rpc_network_inq_protseqs
rpc_string_binding_parse
3.55 – rpc_ns_binding_export
NAME
rpc_ns_binding_export - Establishes a name service database entry
with binding handles or object UUIDs for a
server
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>(
void rpc_ns_binding_export( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
rpc_binding_vector_t *binding_vec,
uuid_vector_t *object_uuid_vec,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the entry_name
parameter.
To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX
logical name, provide the value rpc_c_ns_syntax_default.
entry_name
Specifies the entry name to which binding handles and object UUIDs
are exported. This can be either the global or cell-relative
name.
if_handle
Specifies a stub-generated data structure that identifies the
interface to export. Specifying the value NULL indicates there
are no binding handles to export (only object UUIDs are exported)
and the binding_vec parameter is ignored.
binding_vec
Specifies a vector of server bindings to export. Specify the value
NULL for this parameter in cases where there are no binding
handles to export (only object UUIDs are exported).
object_uuid_vec
Identifies a vector of object UUIDs offered by the server. The
server application constructs this vector. NULL indicates there
are no object UUIDs to export (only binding handles are exported).
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_nothing_to_export
Nothing to export.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_ns_binding_export() routine allows a server application to
publicly offer, in the name service database, an interface that any
client application can use. A server application can also use this
routine to publicly offer the object UUIDs of the application's
resources.
To export an interface, the server application calls the routine with
an interface and the server binding handles that a client can use to
access the server.
A server can export interfaces and objects in a single call to this
routine, or it can export them separately.
If the entry in the name service database specified by the entry_name
parameter does not exist, rpc_ns_binding_export() tries to create it.
In this case a server must have the correct permissions to create the
entry. Otherwise, a management application with the necessary
permissions creates the entry by calling rpc_ns_mgmt_entry_create()
before the server runs.
A server is not required to export its interfaces to the name service
database. When a server does not export any interfaces, only clients
that privately know of that server's binding information can access
its interfaces. For example, a client that has the information needed
to construct a string binding can call
rpc_binding_from_string_binding() to create a binding handle for
making remote procedure calls to a server.
Before calling rpc_ns_binding_export() to export interfaces (but not
to export object UUIDs), a server must do the following:
+ Register one or more protocol sequences with the local RPC
runtime by calling one of the following routines:
rpc_server_use_protseq() rpc_server_use_protseq_ep()
rpc_server_use_protseq_if() rpc_server_use_all_protseqs()
rpc_server_use_all_protseqs_if()
+ Obtain a list of server bindings by calling
rpc_server_inq_bindings(). The vector returned from
rpc_server_inq_bindings() becomes the binding_vec parameter
for this routine. To prevent a binding from being exported,
set the selected vector element to the value NULL.
(See the section on RPC data types and structures in the
rpc_intro reference page.)
If a server exports an interface to the same entry in the name
service database more than once, the second and subsequent calls
to this routine add the binding information and object UUIDs only
if they differ from the ones in the server entry. Existing data
is not removed from the entry.
To remove binding handles and object UUIDs from the name service
database, a server application calls rpc_ns_binding_unexport() and
a management application calls rpc_ns_mgmt_binding_unexport().
For an explanation of how a server can establish a client/server
relationship without using the name service database, see the
explanation of a string binding in the rpc_intro reference page.
In addition to calling this routine, a server that called either
rpc_server_use_all_protseqs() or rpc_server_use_protseq() must also
register with the local endpoint map by calling rpc_ep_register() or
rpc_ep_register_no_replace().
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry). If the entry does not exist,
you also need insert permission to the parent directory.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_unexport
rpc_ns_mgmt_binding_unexport
rpc_ns_mgmt_entry_create
rpc_server_inq_bindings
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
3.56 – rpc_ns_binding_import_begin
NAME
rpc_ns_binding_import_begin - Creates an import context for an
interface and an object in the name
service database
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>(
void rpc_ns_binding_import_begin( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
uuid_t *obj_uuid,
rpc_ns_handle_t *import_context,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of parameter
entry_name. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value
rpc_c_ns_syntax_default.
entry_name
Specifies the entry name where the search for compatible binding
handles begins. This can be either the global or cell-relative
name. To use the entry name found in the RPC_DEFAULT_ENTRY
logical name, supply NULL or a null string (\0) for this
parameter. When this entry name is used, the RPC runtime
automatically uses the default name syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name.
if_handle
A stub-generated data structure specifying the interface to
import. If the interface specification has not been exported or
is of no concern to the caller, specify NULL for this parameter.
In this case the bindings returned are only guaranteed to be of
a compatible and supported protocol sequence and, depending on
the value of parameter obj_uuid, contain the specified object
UUID.The desired interface may not be supported by the contacted
server.
obj_uuid
Specifies an optional object UUID.
If you specify NULL or a nil UUID for this parameter, the
returned binding handles contain one of the object UUIDs that
the compatible server exported. If the server did not export
any object UUIDs, the returned compatible binding handles contain
a nil object UUID.
If you specify a non-nil UUID, compatible binding handles are
returned from an entry only if the server has exported the
specified object UUID. Each returned binding handle contains
the specified non-nil object UUID.
Output
import_context
Returns the name service handle for use with the
rpc_ns_binding_import_next() and rpc_ns_binding_import_done()
routines.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_invalid_object
Invalid object.
rpc_s_no_env_setup
Environment variable not set up.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_binding_import_begin() routine creates an import context
for importing compatible server binding handles for servers. These
servers offer the specified interface and object UUID in the
respective if_handle and obj_uuid parameters.
Before calling rpc_ns_binding_import_next(), the client must first
call this routine to create an import context. The arguments to
this routine control the operation of rpc_ns_binding_import_next().
After importing binding handles, the client calls
rpc_ns_binding_import_done() to delete the import context.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_mgmt_handle_set_exp_age
3.57 – rpc_ns_binding_import_done
NAME
rpc_ns_binding_import_done - Deletes the import context for searching
the name service database
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_binding_import_done( rpc_ns_handle_t *import_context,
unsigned32 *status );
PARAMETERS
Input/Output
import_context
Specifies the name service handle to delete. (A name service
handle is created by calling rpc_ns_binding_import_begin().)
Returns the value NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_ns_handle
Invalid name service handle.
DESCRIPTION
The rpc_ns_binding_import_done() routine deletes an import context
created by calling rpc_ns_binding_import_begin(). This deletion does
not affect any previously imported bindings.
Typically, a client calls this routine after completing remote
procedure calls to a server using a binding handle returned from
rpc_ns_binding_import_next(). A client program calls this routine
for each created import context, regardless of the status returned
from rpc_ns_binding_import_next(), or the success in making remote
procedure calls.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_binding_import_begin
rpc_ns_binding_import_next
3.58 – rpc_ns_binding_import_next
NAME
rpc_ns_binding_import_next - Returns a binding handle of a compatible
server (if found) from the name service
database
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_binding_import_next( rpc_ns_handle_t import_context,
rpc_binding_handle_t *binding,
unsigned32 *status );
PARAMETERS
Input
import_context
Specifies a name service handle. This handle is returned from
the rpc_ns_binding_import_begin() routine.
Output
binding
Returns a compatible server binding handle.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_class_version_mismatch
RPC class version mismatch.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_invalid_ns_handle
Invalid name service handle.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_more_bindings
No more bindings.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_rpc_entry
Not an RPC entry.
DESCRIPTION
The rpc_ns_binding_import_next() routine returns one compatible (to
the client) server binding handle selected at random from the name
service database. The server offers the interface and object UUID
specified by the respective if_handle and obj_uuid parameters in
rpc_ns_binding_import_begin().
A similar routine is rpc_ns_binding_lookup_next(), which returns a
vector of compatible server binding handles for one or more servers.
NOTE: Routine rpc_ns_binding_import_next() calls routine
rpc_ns_binding_lookup_next() which, in turn, obtains a vector
of server binding handles from the name service database.
Next, routine rpc_ns_binding_import_next() randomly selects one
of the elements from the vector.
The rpc_ns_binding_import_next() routine communicates only with the
name service database, not directly with servers.
The returned compatible binding handle always contains an object UUID.
Its value depends on the value specified in the obj_uuid parameter of
the rpc_ns_binding_import_begin() routine, as follows:
+ If obj_uuid contains a non-nil object UUID, the returned binding
handle contains that object UUID.
+ If obj_uuid contains a nil object UUID or NULL, the object UUID
returned in the binding handle depends on how the server exported
object UUIDs:
- If the server did not export any object UUIDs, the returned
binding handle contains a nil object UUID.
- If the server exported one object UUID, the returned binding
handle contains that object UUID.
- If the server exported multiple object UUIDs, the returned
binding handle contains one of the object UUIDs, selected in
an unspecified way.
Applications should not count on multiple calls to
rpc_ns_binding_import_next() returning different object UUIDs.
In particular, note that each name service entry stores server
address information separately from exported object UUIDs.
Successive calls to rpc_ns_binding_import_next() using the same
import context will return exactly one binding for each
compatible server address, not the cross product of all
compatible server addresses with all exported UUIDs. Each
returned binding will contain one of the exported object
UUIDs, but applications should not count on any specific
selection mechanism for these object UUIDs
The client application can use the returned binding handle to make
a remote procedure call to the server. If the client fails to
communicate with the server, it can call the
rpc_ns_binding_import_next() routine again.
Each time the client calls rpc_ns_binding_import_next(), the routine
returns another server binding handle. The binding handles returned
are unordered. Multiple binding handles can refer to different
protocol sequences from the same server.
When the search finishes, the routine returns a status code of
rpc_s_no_more_bindings and returns the value NULL in binding.
A client application calls rpc_ns_binding_inq_entry_name() to obtain
the name of the entry in the name service database where the binding
handle came from.
The rpc_ns_binding_import_next() routine allocates memory for the
returned binding parameter. When a client application finishes with
the binding handle, it must call rpc_binding_free() to deallocate the
memory. Each call to rpc_ns_binding_import_next() requires a
corresponding call to rpc_binding_free().
The client calls the rpc_ns_binding_import_done() routine after it has
satisfactorily used one or more returned server binding handles. The
rpc_ns_binding_import_done() routine deletes the import context. The
client also calls rpc_ns_binding_import_done() if the application
wants to start a new search for compatible servers (by calling
rpc_ns_binding_import_begin()). The order of binding handles returned
can be different for each new search. This means that the order in
which binding handles are returned to an application can be different
each time the application is run.
Permissions Required
You need read permission to the specified CDS object entry (the
starting name service entry) and to any CDS object entry in the
resulting search path.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_inq_entry_name
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_done
rpc_ns_binding_lookup_next
rpc_ns_binding_select
3.59 – rpc_ns_binding_inq_entry_name
NAME
rpc_ns_binding_inq_entry_name - Returns the name of an entry in the
name service database from which the
server binding handle came
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_binding_inq_entry_name( rpc_binding_handle_t binding,
unsigned32 entry_name_syntax,
unsigned_char_t **entry_name,
unsigned32 *status );
PARAMETERS
Input
binding
Specifies a server binding handle whose entry name in the name
service database is returned.
entry_name_syntax
An integer value that specifies the syntax of returned parameter
entry_name.
To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX
logical name, provide the value rpc_c_ns_syntax_default.
Output
entry_name
Returns the name of the entry in the name service database in
which binding was found. The returned name is a global name.
Specify NULL to prevent the routine from returning this parameter.
When you specify this value, the client does not need to call
rpc_string_free().
status
Returns the status code from this routine, which indicates whether
the routine completed successfully or, if not, why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_binding
Invalid binding handle.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_no_entry_name
No entry name for binding.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
rpc_s_wrong_kind_of_binding
Wrong kind of binding for operation.
DESCRIPTION
The rpc_ns_binding_inq_entry_name() routine returns the global name
of the entry in the name service database from which a binding handle
for a compatible server came.
The RPC runtime allocates memory for the string returned in the
entry_name parameter. Your application calls rpc_string_free() to
deallocate that memory.
An entry name is associated only with binding handles returned from
the rpc_ns_binding_import_next(), rpc_ns_binding_lookup_next(), and
rpc_ns_binding_select() routines.
If the binding handle specified in the binding parameter is not
returned from an entry in the name service database (for example,
the binding handle is created by calling
rpc_binding_from_string_binding()), this routine returns the
rpc_s_no_entry_name status code.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_from_string_binding
rpc_ns_binding_import_next
rpc_ns_binding_lookup_next
rpc_ns_binding_select
rpc_string_free
3.60 – rpc_ns_binding_lookup_begin
NAME
rpc_ns_binding_lookup_begin - Creates a lookup context for an
interface and an object in the name
service database
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_binding_lookup_begin( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
uuid_t *object_uuid,
unsigned32 binding_max_count,
rpc_ns_handle_t *lookup_context,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the entry_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value
rpc_c_ns_syntax_default.
entry_name
Specifies the entry name at which the search for compatible
binding handles begins. This can be either the global or cell-
relative name. To use the entry name found in the
RPC_DEFAULT_ENTRY logical name, supply NULL or a null string (\0)
for this parameter. When this entry name is used, the RPC runtime
automatically uses the default name syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name.
if_handle
A stub-generated data structure specifying the interface to look
up. If the interface specification has not been exported or is
of no concern to the caller, specify NULL for this parameter.
In this case the bindings returned are only guaranteed to be of
a compatible and supported protocol sequence and contain the
specified object UUID. The desired interface might not be
supported by the contacted server.
object_uuid
Specifies an optional object UUID.
If you specify NULL or a nil UUID for this parameter, the returned
binding handles contain one of the object UUIDs exported by the
compatible server. If the server did not export any object UUIDs,
the returned compatible binding handles contain a nil object UUID.
For a non-nil UUID, compatible binding handles are returned from
an entry only if the server has exported the specified object
UUID.Each returned binding handle contains the specified non-nil
object UUID.
binding_max_count
Sets the maximum number of bindings to return in the
binding_vector parameter of rpc_ns_binding_lookup_next().
Specify rpc_c_binding_max_count_default to use the default count.
Output
lookup_context
Returns the name service handle for use with the
rpc_ns_binding_lookup_next() and rpc_ns_binding_lookup_done()
routines.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_invalid_object
Invalid object.
rpc_s_no_env_setup
Environment variable not set up.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_binding_lookup_begin() routine creates a lookup context for
locating compatible server binding handles for servers. These servers
offer the specified interface and object UUID in the respective
if_handle and object_uuid parameters.
Before calling rpc_ns_binding_lookup_next(), the client application
must first create a lookup context by calling
rpc_ns_binding_lookup_begin(). The parameters to this routine
control the operation of rpc_ns_binding_lookup_next().
When finished locating binding handles, the client application calls
the rpc_ns_binding_lookup_done() routine to delete the lookup context.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_binding_lookup_done
rpc_ns_binding_lookup_next
rpc_ns_mgmt_handle_set_exp_age
3.61 – rpc_ns_binding_lookup_done
NAME
rpc_ns_binding_lookup_done - Deletes the lookup context for searching
the name service database
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_binding_lookup_done( rpc_ns_handle_t *lookup_context,
unsigned32 *status );
PARAMETERS
Input/Output
lookup_context
Specifies the name service handle to delete. (A name service
handle is created by calling rpc_ns_binding_lookup_begin().)
Returns the value NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_invalid_ns_handle Invalid name service handle.
DESCRIPTION
The rpc_ns_binding_lookup_done() routine deletes a lookup context
created by calling rpc_ns_binding_lookup_begin().
Typically, a client calls this routine after completing remote
procedure calls to a server using a binding handle returned from
rpc_ns_binding_lookup_next(). A client program calls this routine
for each created lookup context, regardless of the status returned
from rpc_ns_binding_lookup_next(), or success in making remote
procedure calls.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_next
3.62 – rpc_ns_binding_lookup_next
NAME
rpc_ns_binding_lookup_next - Returns a list of binding handles of
one or more compatible servers (if
found) from the name service database
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_binding_lookup_next( rpc_ns_handle_t lookup_context,
rpc_binding_vector_t **binding_vec,
unsigned32 *status );
PARAMETERS
Input
lookup_context
Specifies a name service handle. This handle is returned from the
rpc_ns_binding_lookup_begin() routine.
Output
binding_vec
Returns a vector of compatible server binding handles.
status
Returns the status code from this routine, which indicates
whether the routine completed successfully or, if not, why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_class_version_mismatch
RPC class version mismatch.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_invalid_ns_handle
Invalid name service handle.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_more_bindings
No more bindings.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_rpc_entry
Not an RPC entry.
DESCRIPTION
The rpc_ns_binding_lookup_next() routine returns a vector of
compatible (to the client) server binding handles. The servers offer
the interface and object UUID specified by the respective if_handle
and object_uuid parameters in rpc_ns_binding_lookup_begin(). The
number of binding handles that rpc_ns_binding_lookup_next() attempts
to return is the value of binding_max_count in the
rpc_ns_binding_lookup_begin() routine.
A similar routine is rpc_ns_binding_import_next(), which returns one
compatible server binding handle.
The rpc_ns_binding_lookup_next() routine communicates only with the
name service database, not directly with servers.
This routine traverses entries in the name service database, returning
compatible server binding handles from each entry. The routine can
return multiple binding handles from each entry. The search operation
obeys the following rules for traversing the entries:
+ At each entry visited, the search operation randomly processes
binding information, then group members, then profile members.
Profile members with different priorities are returned according
to their priorities, highest priority first.
+ The search operation returns members of a group in random order.
+ The search operation returns members of a profile with the same
priority in random order.
If the entry where the search begins (see the entry_name parameter in
rpc_ns_binding_lookup_begin()) contains binding handles as well as an
RPC group and/or a profile, rpc_ns_binding_lookup_next() returns the
binding handles from entry_name before searching the group or profile.
This means that rpc_ns_binding_lookup_next() can return a partially
full vector before processing the members of the group or profile.
Each binding handle in the returned vector always contains an object
UUID. Its value depends on the value specified in the object_uuid
parameter of rpc_ns_binding_lookup_begin() as follows:
+ If object_uuid contains a non-nil object UUID, each returned
binding handle contains that object UUID.
+ If object_uuid contains a nil object UUID or NULL, the object
UUID returned in each binding handle depends on how the server
exported object UUIDS:
- If the server did not export any object UUIDs, each returned
binding handle contains a nil object UUID.
- If the server exported one object UUID, each returned
binding handle contains that object UUID.
- If the server exported multiple object UUIDs, the returned
binding handle contains one of the object UUIDs, selected
in an unspecified way.
Applications should not count on the binding handles returned
from a given entry to contain different object UUIDs. In
particular, note that each name service entry stores server
address information separately from exported object UUIDs.
One or more calls to rpc_ns_binding_lookup_next() will return
exactly one binding for each compatible server address, not
the cross product of all compatible server addresses with all
exported UUIDs. Each returned binding will contain one of the
exported object UUIDs, but applications should not count on
any specific selection mechanism for these object UUIDs
From the returned vector of server binding handles, the client
application can employ its own criteria for selecting individual
binding handles, or the application can call rpc_ns_binding_select()
to select a binding handle. The rpc_binding_to_string_binding() and
rpc_string_binding_parse() routines are useful for a client creating
its own selection criteria.
The client application can use the selected binding handle to attempt
a remote procedure call to the server. If the client fails to
communicate with the server, it can select another binding handle
from the vector. When all the binding handles in the vector are used,
the client application calls rpc_ns_binding_lookup_next() again.
Each time the client calls rpc_ns_binding_lookup_next(), the routine
returns another vector of binding handles. The binding handles
returned in each vector are unordered, as is the order in which the
vectors are returned from multiple calls to this routine.
When looking up compatible binding handles from a profile, the binding
handles from entries of equal profile priority are unordered in the
returned vector. In addition, the vector returned from a call to
rpc_ns_binding_lookup_next() contains only compatible binding handles
from entries of equal profile priority. This means the returned vector
may be partially full.
For example, if the binding_max_count parameter value in
rpc_ns_binding_lookup_begin() was 5 and rpc_ns_binding_lookup_next()
finds only three compatible binding handles from profile entries of
priority 0 (zero), rpc_ns_binding_lookup_next() returns a partially
full binding vector (with three binding handles). The next call to
rpc_ns_binding_lookup_next() creates a new binding vector and begins
looking for compatible binding handles from profile entries of
priority 1.
When the search finishes, the routine returns a status code of
rpc_s_no_more_bindings and returns the value NULL in binding_vec.
A client application calls rpc_ns_binding_inq_entry_name() to obtain
the name of the entry in the name service database where the binding
handle came from.
The rpc_ns_binding_lookup_next() routine allocates memory for the
returned binding_vec. When a client application finishes with the
vector, it must call rpc_binding_vector_free() to deallocate the
memory. Each call to rpc_ns_binding_lookup_next() requires a
corresponding call to rpc_binding_vector_free().
The client calls rpc_ns_binding_lookup_done(), which deletes the
lookup context. The client also calls rpc_ns_binding_lookup_done()
if the application wants to start a new search for compatible
servers (by calling rpc_ns_binding_lookup_begin()). The order of
binding handles returned can be different for each new search. This
means that the order in which binding handles are returned to an
application can be different each time the application is run.
Permissions Required
You need read permission to the specified CDS object entry (the
starting name service entry) and to any CDS object entry in the
resulting search path.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_to_string_binding
rpc_binding_vector_free
rpc_ns_binding_import_next
rpc_ns_binding_inq_entry_name
rpc_ns_binding_lookup_begin
rpc_ns_binding_lookup_done
rpc_ns_binding_select
rpc_string_binding_parse
3.63 – rpc_ns_binding_select
NAME
rpc_ns_binding_select - Returns a binding handle from a list of
compatible server binding handles
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_binding_select( rpc_binding_vector_t *binding_vec,
rpc_binding_handle_t *binding,
unsigned32 *status );
PARAMETERS
Input/Output
binding_vec
Specifies the vector of compatible server binding handles from
which a binding handle is selected. The returned binding vector
no longer references the selected binding handle (returned
separately in the binding parameter).
Output
binding
Returns a selected server binding handle.
status
Returns the status code from this routine, which indicates whether
the routine completed successfully or, if not, why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_no_more_bindings
No more bindings.
DESCRIPTION
The rpc_ns_binding_select() routine randomly chooses and returns a
server binding handle from a vector of server binding handles.
Each time the client calls rpc_ns_binding_select(), the routine
returns another binding handle from the vector.
When all of the binding handles are returned from the vector, the
routine returns a status code of rpc_s_no_more_bindings and
returns the value NULL in binding.
The select operation allocates storage for the data referenced by the
returned binding parameter. When a client finishes with the binding
handle, it calls rpc_binding_free() to deallocate the storage. Each
call to the rpc_ns_binding_select() routine requires a corresponding
call to rpc_binding_free().
Instead of using this routine, client applications can select a
binding handle according to their specific needs. In this case the
rpc_binding_to_string_binding() and rpc_string_binding_parse()
routines are useful to the applications since the routines work
together to extract the individual fields of a binding handle for
examination.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_free
rpc_binding_to_string_binding
rpc_ns_binding_lookup_next
rpc_string_binding_parse
3.64 – rpc_ns_binding_unexport
NAME
rpc_ns_binding_unexport - Removes the binding handles for an
interface, or object UUIDs, from an
entry in the name service database
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_binding_unexport( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_handle_t if_handle,
uuid_vector_t *object_uuid_vec,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the entry_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the value
rpc_c_ns_syntax_default.
entry_name
Specifies an entry name whose binding handles or object UUIDs are
removed. This can be either the global or cell-relative name.
if_handle
Specifies an interface specification for the binding handles to be
removed from the name service database. The value NULL indicates
that no binding handles are removed (only object UUIDs are
removed).
object_uuid_vec
Specifies a vector of object UUIDs to be removed from the name
service database. The application constructs this vector. The
value NULL indicates that no object UUIDs are removed (only
binding handles are removed).
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_class_version_mismatch
RPC class version mismatch.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_interface_not_found
Interface not found.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_invalid_vers_option
Invalid version option.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_all_objs_unexported
Not all objects unexported.
rpc_s_nothing_to_unexport
Nothing to unexport.
rpc_s_not_rpc_entry
Not an RPC entry.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_binding_unexport() routine allows a server application to
unexport (that is, remove) one of the following from an entry in the
name service database:
+ All the binding handles for an interface.
+ One or more object UUIDs for a resource or resources.
+ Both binding handles and object UUIDs.
The rpc_ns_binding_unexport() routine removes only those binding
handles that match the interface UUID and the major and minor
interface version numbers found in the if_handle parameter. To
remove multiple versions of an interface, use
rpc_ns_mgmt_binding_unexport().
A server application can remove an interface and objects in a single
call to this routine, or it can remove them separately.
If rpc_ns_binding_unexport() does not find any binding handles for
the specified interface, it returns an rpc_s_interface_not_found
status code and does not remove the object UUIDs, if any are
specified.
If one or more binding handles for the specified interface are found
and removed without error, rpc_ns_binding_unexport() removes the
specified object UUIDs, if any.
If any of the specified object UUIDs are not found,
rpc_ns_binding_unexport() returns the status code
rpc_s_not_all_objs_unexported.
A server application, in addition to calling this routine, also calls
rpc_ep_unregister() to unregister any endpoints that the server
previously registered with the local endpoint map.
Use this routine with caution, only when you expect a server to be
unavailable for an extended time; for example, when it is permanently
removed from service.
Additionally, keep in mind that name service databases are designed to
be relatively stable. In replicated name service databases, frequent
use of rpc_ns_binding_export() and rpc_ns_binding_unexport() causes
the name service to remove and replace the same entry repeatedly, and
can cause performance problems.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ep_unregister
rpc_ns_binding_export
rpc_ns_mgmt_binding_unexport
3.65 – rpc_ns_entry_expand_name
NAME
rpc_ns_entry_expand_name - Expands the name of a name service entry
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_entry_expand_name( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
unsigned_char_t **expanded_name,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the entry_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide a value of
rpc_c_ns_syntax_default.
entry_name
Specifies the entry name to expand. This can be either the global
or cell-relative name.
Output
expanded_name
Returns a pointer to the expanded version of entry_name. Do not
specify NULL since the routine always returns a name string.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_incomplete_name Incomplete name.
DESCRIPTION
An application calls rpc_ns_entry_expand_name() to obtain a fully
expanded entry name.
The RPC runtime allocates memory for the returned expanded_name
parameter. The application is responsible for calling
rpc_string_free() for that returned parameter string.
The returned and expanded entry name accounts for local name
translations and differences in locally defined naming schemas.
For example, suppose the entry in the name service is
/.:/subsys/PrintQ/server1
Upon return from rpc_ns_entry_expand_name(),the expanded name could be
/.../abc.com/subsys/PrintQ/server1
For more information about local names and their expansions, see the
information on the DCE Directory Service in the OSF DCE Administration
Guide.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_string_free
Books: OSF DCE Administration Guide.
3.66 – rpc_ns_entry_object_inq_begin
NAME
rpc_ns_entry_object_inq_begin - Creates an inquiry context for viewing
the objects of an entry in the name
service database
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_entry_object_inq_begin( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_ns_handle_t *inquiry_context,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the entry_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide a value of
rpc_c_ns_syntax_default.
entry_name
Specifies the entry in the name service database for which object
UUIDs are viewed. This can be either the global or cell-relative
name.
Output
inquiry_context
Returns a name service handle for use with the
rpc_ns_entry_object_inq_next() routine, and with the
rpc_ns_entry_object_inq_done() routine.
status
Returns the status code from this routine, indicating whether the
routine completed successfully or, if not, why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_entry_object_inq_begin() routine creates an inquiry context
for viewing the object UUIDs exported to entry_name.
Before calling rpc_ns_entry_object_inq_next(), the application must
first call this routine to create an inquiry context.
When finished viewing the object UUIDs, the application calls the
rpc_ns_entry_object_inq_done() routine to delete the inquiry context.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_binding_export
rpc_ns_entry_object_inq_done
rpc_ns_entry_object_inq_next
rpc_ns_mgmt_handle_set_exp_age
3.67 – rpc_ns_entry_object_inq_done
NAME
rpc_ns_entry_object_inq_done - Deletes the inquiry context for viewing
the objects of an entry in the name
service database
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_entry_object_inq_done( rpc_ns_handle_t *inquiry_context,
unsigned32 *status );
PARAMETERS
Input/Output
inquiry_context
Specifies the name service handle to delete. (A name service
handle is created by calling rpc_ns_entry_object_inq_begin().)
Returns the value NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_ns_handle
Invalid name service handle.
DESCRIPTION
The rpc_ns_entry_object_inq_done() routine deletes an inquiry context
created by calling rpc_ns_entry_object_inq_begin().
An application calls this routine after viewing exported object UUIDs
using the rpc_ns_entry_object_inq_next() routine.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_entry_object_inq_begin
rpc_ns_entry_object_inq_next
3.68 – rpc_ns_entry_object_inq_next
NAME
rpc_ns_entry_object_inq_next - Returns one object at a time from an
entry in the name service database
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_entry_object_inq_next( rpc_ns_handle_t inquiry_context,
uuid_t *obj_uuid,
unsigned32 *status );
PARAMETERS
Input
inquiry_context
Specifies a name service handle. This handle is returned from the
rpc_ns_entry_object_inq_begin() routine.
Output
obj_uuid
Returns an exported object UUID.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_class_version_mismatch
RPC class version mismatch.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_ns_handle
Invalid name service handle.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_more_members
No more members.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_rpc_entry
Not an RPC entry.
DESCRIPTION
The rpc_ns_entry_object_inq_next() routine returns one of the object
UUIDs exported to an entry in the name service database. The
entry_name parameter in the rpc_ns_entry_object_inq_begin() routine
specified the entry.
An application can view all of the exported object UUIDs by repeatedly
calling the rpc_ns_entry_object_inq_next() routine. When all the
object UUIDs are viewed, this routine returns an rpc_s_no_more_members
status. The returned object UUIDs are unordered.
The application supplies the memory for the object UUID returned in
the obj_uuid parameter.
After viewing the object UUIDs, the application must call the
rpc_ns_entry_object_inq_done() routine to delete the inquiry context.
The order in which rpc_ns_entry_object_inq_next() returns object UUIDs
can be different for each viewing of an entry. Therefore, the order
in which an application receives object UUIDs can be different each
time the application is run.
Permissions Required
You need read permission to the CDS object entry (the target name
service entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_binding_export
rpc_ns_entry_object_inq_begin
rpc_ns_entry_object_inq_done
3.69 – rpc_ns_group_delete
NAME
rpc_ns_group_delete - Deletes a group attribute
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_group_delete( unsigned32 group_name_syntax,
unsigned_char_t *group_name,
unsigned32 *status );
PARAMETERS
Input
group_name_syntax
An integer value that specifies the syntax of the group_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide the integer value
rpc_c_ns_syntax_default.
group_name
Specifies the RPC group to delete. This can be either the global
or cell-relative name.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_group_delete() routine deletes the group attribute from the
specified entry in the name service database.
Neither the specified entry nor the entries represented by the group
members are deleted.
Permissions Required
You need write permission to the CDS object entry (the target group
entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_group_member_add
rpc_ns_group_member_delete
3.70 – rpc_ns_group_mbr_add
NAME
rpc_ns_group_mbr_add - Adds an entry name to a group; if necessary,
creates the entry
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_group_mbr_add( unsigned32 group_name_syntax,
unsigned_char_t *group_name,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
unsigned32 *status );
PARAMETERS
Input
group_name_syntax
An integer value that specifies the syntax of the group_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
group_name
Specifies the RPC group that receives a new member. This can be
either the global or cell-relative name.
member_name_syntax
An integer value that specifies the syntax of member_name.
To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX
logical name, provide rpc_c_ns_syntax_default.
member_name
Name of the new RPC group member. This can be either the global
or cell-relative name.
Output
status
Returns the status code from this routine, indicating whether
the routine completed successfully or, if not, why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_class_version_mismatch
RPC class version mismatch.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_group_mbr_add() routine adds, to the name service database,
an entry name as a member to the Name Service Interface (NSI) group
attribute of an entry. The group_name parameter specifies the entry.
If the specified group_name entry does not exist, this routine creates
the entry with a group attribute and adds the group member specified
by the member_name parameter. In this case, the application must have
permission to create the entry. Otherwise, a management application
with the necessary permissions creates the entry by calling
rpc_ns_mgmt_entry_create() before the application is run.
An application can add the entry in member_name to a group before it
creates the entry itself.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target group entry). If the entry does not exist, you
also need insert permission to the parent directory.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_group_mbr_remove
rpc_ns_mgmt_entry_create
3.71 – rpc_ns_group_mbr_inq_begin
NAME
rpc_ns_group_mbr_inq_begin - Creates an inquiry context for viewing
group members
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_group_mbr_inq_begin( unsigned32 group_name_syntax,
unsigned_char_t *group_name,
unsigned32 member_name_syntax,
rpc_ns_handle_t *inquiry_context,
unsigned32 *status );
PARAMETERS
Input
group_name_syntax
An integer value that specifies the syntax of the group_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
group_name
Specifies the name of the RPC group to view.
member_name_syntax
An integer value that specifies the syntax of member_name in the
rpc_ns_group_mbr_inq_next() routine.
To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX
logical name, provide rpc_c_ns_syntax_default.
Output
inquiry_context
Returns a name service handle for use with the
rpc_ns_group_mbr_inq_next() and rpc_ns_group_mbr_inq_done()
routines.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_group_mbr_inq_begin() routine creates an inquiry context
for viewing the members of an RPC group.
Before calling rpc_ns_group_mbr_inq_next(), the application must first
call this routine to create an inquiry context.
When finished viewing the RPC group members, the application calls
the rpc_ns_group_mbr_inq_done() routine to delete the inquiry context.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_group_mbr_add
rpc_ns_group_mbr_inq_done
rpc_ns_group_mbr_inq_next
rpc_ns_mgmt_handle_set_exp_age
3.72 – rpc_ns_group_mbr_inq_done
NAME
rpc_ns_group_mbr_inq_done - Deletes the inquiry context for a group
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_group_mbr_inq_done( rpc_ns_handle_t *inquiry_context,
unsigned32 *status );
PARAMETERS
Input/Output
inquiry_context
Specifies the name service handle to delete. (A name service
handle is created by calling rpc_ns_group_mbr_inq_begin().)
Returns the value NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_ns_handle Invalid name service handle.
DESCRIPTION
The rpc_ns_group_mbr_inq_done() routine deletes an inquiry context
created by calling rpc_ns_group_mbr_inq_begin().
An application calls this routine after viewing RPC group members
using the rpc_ns_group_mbr_inq_next() routine.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_group_mbr_inq_begin
rpc_ns_group_mbr_inq_next
3.73 – rpc_ns_group_mbr_inq_next
NAME
rpc_ns_group_mbr_inq_next - Returns one member name at a time from
a group
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_group_mbr_inq_next( rpc_ns_handle_t inquiry_context,
unsigned_char_t **member_name,
unsigned32 *status );
PARAMETERS
Input
inquiry_context
Specifies a name service handle. This handle is returned from the
rpc_ns_group_mbr_inq_begin() routine.
Output
member_name
Returns a pointer to a (global) RPC group member name.
The syntax of the returned name is specified by the
member_name_syntax parameter in rpc_ns_group_mbr_inq_begin().
Specify NULL to prevent the routine from returning this parameter.
In this case, the application does not call rpc_string_free().
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_class_version_mismatch
RPC class version mismatch.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_invalid_ns_handle
Invalid name service handle.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_more_members
No more members.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_rpc_entry
Not an RPC entry.
DESCRIPTION
The rpc_ns_group_mbr_inq_next() routine returns one member of
the RPC group specified by the group_name parameter in the
rpc_ns_group_mbr_inq_begin() routine.
An application can view all the members of an RPC group by calling the
rpc_ns_group_mbr_inq_next() routine repeatedly. When all the group
members have been viewed, this routine returns an
rpc_s_no_more_members status. The returned group members are
unordered.
On each call to this routine that returns a member name (as a global
name), the RPC runtime allocates memory for the returned member_name.
The application calls rpc_string_free() for each returned member_name
string.
After viewing the RPC group's members, the application must call the
rpc_ns_group_mbr_inq_done() routine to delete the inquiry context.
Permissions Required
You need read permission to the CDS object entry (the target group
entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_group_mbr_inq_begin
rpc_ns_group_mbr_inq_done
rpc_string_free
3.74 – rpc_ns_group_mbr_remove
NAME
rpc_ns_group_mbr_remove - Removes an entry name from a group
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_group_mbr_remove( unsigned32 group_name_syntax,
unsigned_char_t *group_name,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
unsigned32 *status );
PARAMETERS
Input
group_name_syntax
An integer value that specifies the syntax of the group_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
group_name
Specifies the RPC group from which to remove member_name. This
can be either the global or cell-relative name.
member_name_syntax
An integer value that specifies the syntax of member_name.
To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX
logical name, provide rpc_c_ns_syntax_default.
member_name
Specifies the member to remove from the Name Service Interface
(NSI) group attribute in the group_name entry. This member can
be either the global or cell-relative name.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_group_member_not_found
Group member not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_group_mbr_remove() routine removes a member from the NSI
group attribute in the group_name entry.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target group entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_group_mbr_add
3.75 – rpc_ns_import_ctx_add_eval
NAME
rpc_ns_import_ctx_add_eval - Adds an evaluation routine to an import
context
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_import_ctx_add_eval( rpc_ns_handle_t *import_context,
unsigned32 function_type,
rpc_ns_handle_t *eval_args,
void *eval_func,
void *free_func,
error_status_t *status );
PARAMETERS
Input
import_context
The name service handle obtained from the
rpc_ns_binding_import_begin() routine.
func_type
The type of evaluation function. This value currently must be
rpc_cs_code_eval_func.
eval_args
An opaque data type that data used by the evaluation routine.
Client applications adding a DCE RPC code sets evaluation routine
(rpc_cs_eval_with_universal() or rpc_cs_eval_without_universal())
specify the server's NSI entry name in this parameter.
eval_func
A function pointer to the evaluation routine to be called from
the rpc_ns_binding_import_next() routine. The void declaration
for eval_func means that the function does not return a value.
Client applications adding a DCE RPC code sets evaluation routine
(rpc_cs_eval_with_universal() or rpc_cs_eval_without_universal())
specify the routine name in this parameter.
free_func
A function pointer to a routine that is invoked from
rpc_ns_binding_import_done() and which performs application-
specific cleanup. Client applications adding a DCE RPC code sets
evaluation routine (rpc_cs_eval_with_universal() or
rpc_cs_eval_without_universal()) specify NULL in this parameter.
Output
import_context
Returns the name service handle which contains the
rpc_ns_binding_import_next() and rpc_ns_binding_import_done()
routines.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not.
rpc_s_ok Success.
rpc_s_no_memory
The RPC runtime could not allocate heap storage.
rpc_s_invalid_ns_handle
The import_context parameter was not valid.
DESCRIPTION
The rpc_ns_import_ctx_add_eval() routine adds an evaluation routine to
an import context created by the rpc_ns_binding_import_begin()
routine. The evaluation routine adds additional criteria to that used
by rpc_ns_binding_import_next() (that is, protocol and interface
information) for importing compatible server binding handles. Client
applications call the rpc_ns_import_ctx_add_eval() routine once for
each evaluation routine to be added to an import context (if there are
multiple evaluation routines to be set up.)
If the user-specified evaluation routine needs to perform special
cleanup functions, such as deleting a temporary file from a disk,
use the free_func parameter to specify the cleanup routine to be
called from rpc_ns_binding_import_done().
For DCE 1.1, client applications that transfer international character
data in a heterogeneous character set and code set environment use the
rpc_ns_import_ctx_add_eval() routine to add one or more code sets
evaluation routines to the import context returned by the
rpc_ns_binding_import_begin() routine. When the client application
calls the rpc_ns_binding_import_next() routine to import compatible
binding handles for servers, this routine calls the code sets
evaluation routine, which applies client-server character set and
code sets compatibility checking as another criteria for compatible
binding selection.
The code sets compatibility evaluation routine specified can be one
of the following:
rpc_cs_eval_with_universal
A DCE RPC code sets evaluation routine that evaluates character
set and code sets compatibility between client and server. If
client and server character sets are compatible, but their
supported code sets are not, the routine sets code set tags that
direct the client and/or server stubs to convert character data
to either user-defined intermediate code sets (if they exist) or
the DCE intermediate code set, which is the ISO 10646
(or "universal") code set.
rpc_cs_eval_without_universal
A DCE RPC code sets evaluation routine that evaluates
character set and code sets compatibility between client and
server. If client and server character sets are compatible,
but their supported code sets are not, the routine attempts to
return the message rpc_s_no_compat_codesets to the
rpc_ns_binding_import_next() routine.
application-supplied-routine
A user-written code sets evaluation routine. Application
developers writing internationalized DCE applications can develop
their own code sets evaluation routines for client-server code
sets evaluation if the DCE-supplied routines do not meet their
application's needs.
Restrictions
Client applications that add evaluation routines to server binding
import context cannot use the automatic binding method to bind to a
server.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_cs_eval_with_universal
rpc_cs_eval_without_universal
rpc_ns_binding_import_begin
rpc_ns_binding_import_done
rpc_ns_binding_import_next
rpc_ns_mgmt_handle_set_exp_age
3.76 – rpc_ns_mgmt_binding_unexport
NAME
rpc_ns_mgmt_binding_unexport - Removes multiple binding handles, or
object UUIDs, from an entry in the
name service database
Used by management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_binding_unexport( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_id_t *if_id,
unsigned32 vers_option,
uuid_vector_t *object_uuid_vec,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the
entry_name parameter. To use the syntax specified
in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
entry_name
Specifies an entry name whose binding handles or object UUIDs are
removed. This can be either the global or cell-relative name.
if_id
Specifies an interface identifier for the binding handles to be
removed from the name service database. The value NULL indicates
that no binding handles are removed (only object UUIDs are
removed).
vers_option
Specifies how the rpc_ns_mgmt_binding_unexport() routine uses the
vers_major and the vers_minor fields of the if_id parameter.
The following table presents the accepted values for this parameter:
Uses of vers_major and vers_minor fields of if_id
_____________________________________________________________________
Value Description
_____________________________________________________________________
rpc_c_vers_all Unexports (removes) all bindings
for the interface UUID in if_id,
regardless of the version
numbers. For this value,
specify 0 (zero) for both the
major and minor versions in if_id.
rpc_c_vers_compatible Removes those bindings for the
interface UUID in if_id with the
same major version as in if_id,
and with a minor version greater
than or equal to the minor ver-
sion in if_id.
rpc_c_vers_exact Removes those bindings for the
interface UUID in if_id with the
same major and minor versions as
in if_id.
rpc_c_vers_major_only Removes those bindings for the
interface UUID in if_id with the
same major version as in if_id
(ignores the minor version).
For this value, specify 0 (zero)
for the minor version in if_id.
rpc_c_vers_upto Removes those bindings that
offer a version of the specified
interface UUID less than or
equal to the specified major and
minor version. (For example, if
if_id contains V2.0 and the name
service entry contains binding
handles with the versions V1.3,
V2.0, and V2.1, the rpc_ns_mgmt-
_binding_unexport() routine
removes the binding handles with
V1.3 and V2.0.)
object_uuid_vec
Specifies a vector of object UUIDs to be removed from the name
service database. The application constructs this vector. The
value NULL indicates that no object UUIDs are removed (only
binding handles are removed).
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_interface_not_found
Interface not found.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_invalid_vers_option
Invalid version option.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_all_objs_unexported
Not all objects unexported.
rpc_s_nothing_to_unexport
Nothing to unexport.
rpc_s_not_rpc_entry
Not an RPC entry.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_mgmt_binding_unexport() routine allows a management
application to unexport (that is, remove) one of the following from
an entry in the name service database:
+ All the binding handles for a specified interface UUID, qualified
by the interface version numbers (major and minor).
+ One or more object UUIDs of resources.
+ Both binding handles and object UUIDs of resources.
A management application can remove an interface and objects in a
single call to this routine, or it can remove them separately.
If the rpc_ns_mgmt_binding_unexport() routine does not find any
binding handles for the specified interface, the routine returns
an rpc_s_interface_not_found status and does not remove the object
UUIDs, if any are specified.
If one or more binding handles for the specified interface are found
and removed without error, rpc_ns_mgmt_binding_unexport() removes the
specified object UUIDs, if any.
If any of the specified object UUIDs are not found,
rpc_ns_mgmt_binding_unexport() returns the rpc_not_all_objs_unexported
status code.
A management application, in addition to calling this routine, also
calls the rpc_mgmt_ep_unregister() routine to remove any servers that
have registered with the local endpoint map.
Use this routine with caution, only when you expect a server to be
unavailable for an extended time; for example, when it is permanently
removed from service.
Additionally, keep in mind that name service databases are designed to
be relatively stable. In replicated name service databases, frequent
use of the rpc_ns_binding_export() and rpc_ns_mgmt_binding_unexport()
routines causes the name service to remove and replace the same entry
repeatedly, and can cause performance problems.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_mgmt_ep_unregister
rpc_ns_binding_export
rpc_ns_binding_unexport
3.77 – rpc_ns_mgmt_entry_create
NAME
rpc_ns_mgmt_entry_create - Creates an entry in the name service
database
Used by management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_entry_create( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the entry_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
entry_name
Specifies the name of the entry to create. This can be either
the global or cell-relative name.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_entry_already_exists
Name service entry already exists.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_mgmt_entry_create() routine creates an entry in the name
service database.
A management application can call rpc_ns_mgmt_entry_create() to create
an entry in the name service database for use by another application
that does not itself have the necessary name service permissions to
create an entry.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target name service entry). You also need insert
permission to the parent directory.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_mgmt_entry_delete
3.78 – rpc_ns_mgmt_entry_delete
NAME
rpc_ns_mgmt_entry_delete - Deletes an entry from the name service
database
Used by management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_entry_delete( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the entry_name
parameter. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
entry_name
Specifies the name of the entry to delete. This can be either the
global or cell-relative name.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_rpc_entry
Not an RPC entry.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_mgmt_entry_delete() routine removes an RPC entry from the
name service database.
Management applications use this routine only when an entry is no
longer needed, such as when a server is permanently removed from
service. If the entry is a member of a group or profile, it must
also be deleted from the group or profile.
Use this routine cautiously. Since name service databases are
designed to be relatively stable, the frequent use of
rpc_ns_mgmt_entry_delete() can result in the following difficulties:
+ Performance problems
Creating and deleting entries in client or server applications
causes the name service to remove and replace the same entry
repeatedly in the name service database, which can lead to
performance problems.
+ Lost entry updates
When multiple applications access a single entry through
different replicas of a name service database, updates to the
entry can be lost. In this situation, if one application
deletes the entry and another application updates the entry
before the replicas are synchronized, the delete operation
takes precedence over the update operation. When the replicas
are synchronized, the update is lost because the entry is
deleted from all replicas.
Permissions Required
You need read permission to the CDS object entry (the target name
service entry). You also need delete permission to the CDS object
entry or to the parent directory.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_mgmt_entry_create
3.79 – rpc_ns_mgmt_entry_inq_if_ids
NAME
rpc_ns_mgmt_entry_inq_if_ids - Returns the list of interfaces
exported to an entry in the name
service database
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_entry_inq_if_ids( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_if_id_vector_t **if_id_vec,
unsigned32 *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of argument entry_name.
To use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX
logical name, provide rpc_c_ns_syntax_default.
entry_name
Specifies the entry in the name service database for which an
interface identifier vector is returned. This can be either the
global or cell-relative name.
Output
if_id_vec
Returns the address of the interface identifier vector.
status
Returns the status code from this routine, indicating whether the
routine completed successfully or, if not, why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_interfaces_exported
No interfaces were exported to entry.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_mgmt_entry_inq_if_ids() routine returns an interface
identifier vector containing the interfaces of binding handles
exported to argument entry_name.
This routine uses an expiration age of 0 (zero) to cause an immediate
update of the local copy of name service data. The
rpc_ns_mgmt_inq_exp_age() routine's reference page contains an
explanation of the expiration age.
The application calls rpc_if_id_vector_free() to release memory used
by the returned vector.
Permissions Required
You need read permission to the CDS object entry (the target name
service entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_if_id_vector_free
rpc_if_inq_id
rpc_ns_binding_export
3.80 – rpc_ns_mgmt_free_codesets
NAME
rpc_ns_mgmt_free_codesets - Frees a code sets array that has been
allocated by the RPC runtime
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_free_codesets( rpc_codeset_mgmt_p_t *code_sets_array,
error_status_t *status );
PARAMETERS
Input/Output
code_sets_array
A pointer to a code sets array that has been allocated by a
call to the rpc_ns_mgmt_read_codesets() routine or the
rpc_rgy_get_codesets() routine.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
DESCRIPTION
The rpc_ns_mgmt_free_codesets() routine belongs to a set of DCE RPC
routines for character and code set interoperability. These routines
permit client and server applications to transfer international
character data in a heterogeneous character set and code sets
environment.
The rpc_ns_mgmt_free_codesets() routine frees from the client
application's memory a code sets array allocated by a client call to
the rpc_ns_mgmt_read_codesets() or the rpc_rgy_get_codesets()
routines. The routine frees from a server application's memory a
code sets array allocated by a server call to the
rpc_rgy_get_codesets() routine.
Client applications use the rpc_ns_mgmt_read_codesets() routine to
retrieve a server's supported code sets in order to evaluate them
against the code sets that the client supports. Clients and servers
use the rpc_rgy_get_codesets() routine to get their supported code
sets from the code set registery. Clients and servers use the
rpc_ns_mgmt_free_codesets() routine to free the memory allocated to
the code sets array as part of their cleanup procedures.
Permissions Required
None.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_mgmt_read_codesets
rpc_rgy_get_codesets
3.81 – rpc_ns_mgmt_handle_set_exp_age
NAME
rpc_ns_mgmt_handle_set_exp_age - Sets a handle's expiration age for
local copies of name service data
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_handle_set_exp_age( rpc_ns_handle_t ns_handle,
unsigned32 expiration_age,
unsigned32 *status );
PARAMETERS
Input
ns_handle
Specifies the name service handle for which you supply an
expiration age. An RPC Name Service Interface (NSI) inquiry
begin operation returns a name service handle. An example is
the operation that rpc_ns_entry_object_inq_begin() performs; it
returns a name service handle in its inquiry_context parameter.
expiration_age
This integer value specifies the expiration age, in seconds, of
local name service data. This data is read by all RPC NSI next
routines that use the specified ns_handle parameter. An example
is the rpc_ns_entry_object_inq_next() routine; it accepts a name
service handle in its inquiry_context parameter. An expiration
age of 0 (zero) causes an immediate update of the local name
service data.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_ns_handle Invalid name service handle.
DESCRIPTION
The rpc_ns_mgmt_handle_set_exp_age() routine sets an expiration age
for a specified name service handle (in ns_handle). The expiration
age is the amount of time, in seconds, that a local copy of data from
a name service attribute can exist, before a request from the
application for the attribute requires updating the local copy.
When an application begins running, the RPC runtime specifies
a random value of between 8 and 12 hours as the default expiration
age. The default is global to the application. An expiration age
applies only to a specific name service handle and temporarily
overrides the current global expiration age.
Normally, avoid using this routine; instead, rely on the application's
global expiration age.
A handle's expiration age is used exclusively by RPC NSI next
operations (which read data from name service attributes). A next
operation normally starts by looking for a local copy of the
attribute data being requested by an application. In the absence of
a local copy, the next operation creates one with fresh attribute
data from the name service database. If a local copy already exists,
the operation compares its actual age to the expiration age being
used by the application (which in this case is the expiration age
set for the name service handle). If the actual age exceeds the
handle's expiration age, the operation automatically tries to update
the local copy with fresh attribute data. If updating is impossible,
the old local data remains in place and the next operation fails,
returning the rpc_s_name_service_unavailable status code.
The scope of a handle's expiration age is a single series of RPC NSI
next operations. The rpc_ns_mgmt_handle_set_exp_age() routine
operates as follows:
1. An RPC NSI begin operation, such as the one performed by
rpc_ns_group_mbr_inq_begin() creates a name service handle.
2. A call to rpc_ns_mgmt_handle_set_exp_age() creates an expiration
age for the handle.
3. A series of corresponding RPC NSI next operations for the name
service handle uses the handle's expiration age.
4. A corresponding RPC NSI done operation for the name service
handle deletes both the handle and its expiration age.
Permissions Required
No permissions are required.
CAUTIONS
Use this routine with extreme caution.
Setting the handle's expiration age to a small value causes the RPC
NSI next operations to frequently update local data for any name
service attribute requested by your application. For example, setting
the expiration age to 0 (zero) forces the next operation to update
local data for the name service attribute requested by your
application. Therefore, setting a small expiration age for a name
service handle can create performance problems for your application.
Also, if your application is using a remote server with the name
service database, a small expiration age can adversely affect network
performance for all applications.
Limit the use of this routine to the following types of situations:
+ When you must always get accurate name service data. For example,
during management operations to update a profile, you may need to
always see the profile's current contents. In this case, before
beginning to inquire about a profile, your application must call
rpc_ns_mgmt_handle_set_exp_age() and specify 0 (zero) for the
expiration_age parameter.
+ When a request using the default expiration age fails, and your
application needs to retry the operation. For example, a client
application using import must first try to obtain bindings using
the application's default expiration age. However, sometimes the
import-next operation returns either no binding handles or an
insufficient number of them. In this case, the client can retry
the import operation and, after rpc_ns_binding_import_begin()
terminates, include a rpc_ns_mgmt_handle_set_exp_age() routine
that specifies 0 (zero) for the expiration_age parameter. When
the client calls the import-next routine again, the small
expiration age for the name service handle causes the import-next
operation to update the local attribute data.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_binding_import_begin
rpc_ns_binding_lookup_begin
rpc_ns_entry_object_inq_begin
rpc_ns_group_mbr_inq_begin
rpc_ns_mgmt_inq_exp_age
rpc_ns_mgmt_set_exp_age
rpc_ns_profile_elt_inq_begin
3.82 – rpc_ns_mgmt_inq_exp_age
NAME
rpc_ns_mgmt_inq_exp_age - Returns the application's global expiration
age for local copies of name service data
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_inq_exp_age( unsigned32 *expiration_age,
unsigned32 *status );
PARAMETERS
Input
None.
Output
expiration_age
Returns the default expiration age (in seconds). All the RPC Name
Service Interface (NSI) read operations (all the next operations)
use this value.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status code and its meaning is as follows:
rpc_s_ok Success.
DESCRIPTION
The rpc_ns_mgmt_inq_exp_age() routine returns the global expiration
age that the application is using. The expiration_age parameter
represents the amount of time, in seconds, that a local copy of data
from a name service attribute can exist before a request from the
application for the attribute requires updating the local copy. When
an application begins running, the RPC runtime specifies a random
value of between 8 and 12 hours as the default expiration age. The
default is global to the application.
The RPC NSI next operations, which read data from name service
attributes, use an expiration age. A next operation normally starts
by looking for a local copy of the attribute data that an application
requests. In the absence of a local copy, the next operation creates
one with fresh attribute data from the name service database. If a
local copy already exists, the operation compares its actual age to
the expiration age being used by the application. If the actual age
exceeds the expiration age, the operation automatically tries to
update the local copy with fresh attribute data from the name service
database. If updating is impossible, the old local data remains in
place and the next operation fails, returning the
rpc_s_name_service_unavailable status code.
Applications normally use only the default expiration age. For special
cases, an application can substitute a user-supplied global expiration
age for the default by calling rpc_ns_mgmt_set_exp_age(). The
rpc_ns_mgmt_inq_exp_age() routine returns the current global
expiration age, whether it is a default or a user-supplied value.
An application can also override the global expiration age temporarily
by calling rpc_ns_mgmt_handle_set_exp_age().
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_mgmt_handle_set_exp_age
rpc_ns_mgmt_set_exp_age
3.83 – rpc_ns_mgmt_read_codesets
NAME
rpc_ns_mgmt_read_codesets - Reads the code sets attribute associated
with an RPC server entry in the name
service database.
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_read_codesets( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
rpc_codeset_mgmt_p_t *code_sets_array,
error_status_t *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the
entry_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
entry_name
Specifies the name of the RPC server entry in the name service
database from which to read the code sets attribute. The name can
be either the global or cell-relative name.
Output
code_sets_array
A code sets array that specifies the code sets that the RPC server
supports.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok
rpc_s_invalid_name_syntax
rpc_s_mgmt_bad_type
rpc_s_name_service_unavailable
rpc_s_no_permission
rpc_s_incomplete_name
rpc_s_no_memory
DESCRIPTION
The rpc_ns_mgmt_read_codesets() routine belongs to a set of DCE RPC
routines for character and code set interoperability. These routines
permit client and server applications to transfer international
character data in a heterogeneous character set and code sets
environment.
The rpc_ns_mgmt_read_codesets() routine reads the code sets attribute
associated with an RPC server entry in the name service database. The
routine takes the name of an RPC server entry and returns a code sets
array that corresponds to the code sets that this RPC server supports.
Client applications use the rpc_ns_mgmt_read_codesets() routine to
retrieve a server's supported code sets in order to evaluate them
against the code sets that the client supports. Client applications
that use the evaluation routines rpc_cs_eval_with_universal() and
rpc_cs_eval_without_universal() do not need to call this routine
explicitly, because these code sets evaluation routines call it on
the client's behalf. Application developers who are writing their own
character and code set evaluation routines may need to include
rpc_ns_mgmt_read_codesets() in their user-written evaluation routines.
Permissions Required
You need read permission to the target RPC server entry (which is a
CDS object).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: dce_cs_rgy_to_loc
dce_cs_loc_to_rgy
rpc_ns_mgmt_free_codesets
rpc_ns_mgmt_remove_attribute
rpc_ns_mgmt_set_attribute
rpc_rgy_get_codesets
rpc_rgy_get_max_bytes
3.84 – rpc_ns_mgmt_remove_attribute
NAME
rpc_ns_mgmt_remove_attribute - Removes an attribute from an RPC
server entry in the name service
database.
Used mainly by server applications; can also be used by management
applications.
SYNOPSIS
#include <dce/rpc.h>
#include <dce/nsattrid.h>
void rpc_ns_mgmt_remove_attribute( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
uuid_t *attr_type,
error_status_t *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the
entry_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
entry_name
Specifies the name of the RPC server entry in the name service
database from which the attribute will be removed. The name can be
either the global or cell-relative name. If you are using this
routine to remove a code sets attribute from an RPC server entry
in the Cell Directory Service database, then this parameter
specifies the CDS name of the server entry that contains the code
sets attribute to be removed.
attr_type
A UUID that specifies the attribute type. For DCE 1.1, this value
must be rpc_c_attr_codesets.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_entry_not_found
The routine cannot find the RPC server entry
specified in the call in the name service database.
rpc_s_incomplete_name
The routine cannot expand the RPC server entry name
specified in the call.
rpc_s_invalid_name_syntax
The name syntax specified in the call is not valid.
rpc_s_mgmt_bad_type
The attribute type specified in the call does not
match that of the attribute to be removed from the
name service database.
rpc_s_name_service_unavailable
The routine was unable to communicate with the name
service.
rpc_s_no_ns_permission
The routine's caller does not have the proper
permission for an NSI operation.
DESCRIPTION
The rpc_ns_mgmt_remove_attribute() routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous character
set and code sets environment.
The rpc_ns_mgmt_remove_attribute() routine is designed to be a generic
routine for removing an attribute from an RPC server entry in the name
service database. The routine removes the attribute from the
specified RPC server entry in the name service database. The routine
does not remove the RPC server entry.
For DCE 1.1, you use rpc_ns_mgmt_remove_attribute() in your
application server initialization routine or signal handling routine
to remove a code sets attribute from the server's entry in the Cell
Directory Service database as part of the server cleanup procedure
carried out prior to the server's termination.
A management application can call rpc_ns_mgmt_remove_attribute() to
remove an attribute from an RPC server entry in the name service
database on behalf of an application that does not itself have the
necessary name service permissions to remove one.
Permissions Required
You need write permission to the target RPC server entry (which is a
CDS object).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_mgmt_read_codesets
rpc_ns_mgmt_set_attribute
rpc_rgy_get_codesets
3.85 – rpc_ns_mgmt_set_attribute
NAME
rpc_ns_mgmt_set_attribute - Adds an attribute to an RPC server entry
in the name service database.
Used mainly by server applications; can also be used by management
applications.
SYNOPSIS
#include <dce/rpc.h>
#include <dce/nsattrid.h>
void rpc_ns_mgmt_set_attribute( unsigned32 entry_name_syntax,
unsigned_char_t *entry_name,
uuid_t *attr_type,
void *attr_value,
error_status_t *status );
PARAMETERS
Input
entry_name_syntax
An integer value that specifies the syntax of the
entry_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
entry_name
Specifies the name of the RPC server entry in the name service
database with which the attribute will be associated. The name
can be either the global or cell-relative name. If you are using
this routine to add a code sets attribute to an RPC server entry
in the name service database, then this parameter specifies the
name of the server entry with which the code sets attribute will
be associated.
attr_type
A UUID that specifies the attribute type. For DCE 1.1, this value
must be rpc_c_attr_codesets.
attr_val
An opaque data structure that specifies the attribute value to be
stored in the name service database. If you are using this routine
to add a code sets attribute to an RPC server entry, you must cast
the representation of the code set data from the data type
rpc_codeset_mgmt_p_t to the data type void*.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_name_syntax
The name syntax specified in the call is not valid.
rpc_s_mgmt_bad_type
The attribute type specified in the call does not
match that of the attribute to be added to the name
service database.
rpc_s_no_memory
The routine was unable to allocate memory to encode
the value.
rpc_s_name_service_unavailable
The routine was unable to communicate with the name
service.
rpc_s_no_ns_permission
The routine's caller does not have the proper
permission for an NSI operation.
DESCRIPTION
The rpc_ns_mgmt_set_attribute() routine belongs to a set of DCE
RPC routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment.
The rpc_ns_mgmt_set_attribute() routine is designed to be a generic
routine for adding an attribute to an RPC server entry in the name
service database. The routine takes an attribute type and a pointer
to the value, and stores the attribute value in the name service
database.
For DCE 1.1, you use rpc_ns_mgmt_set_attribute() in your application
server initialization routine to add a code sets attribute to the
server's entry in the Cell Directory Service database (which the
initialization routine has created with the rpc_ns_binding_export()
routine). Because CDS stores integer values in little-endian format,
the rpc_ns_mgmt_set_attribute() routine also encodes the code sets
attribute value into an endian-safe format before storing it in the
name service database.
A management application can call rpc_ns_mgmt_set_attribute() to add
an attribute to an RPC server entry in the name service database on
behalf of an application that does not itself have the necessary name
service permissions to add one.
Permissions Required
You need both read permission and write permission to the target RPC
server entry (which is a CDS object). You also need insert permission
to the parent directory.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_mgmt_read_codesets
rpc_ns_mgmt_remove_attribute
rpc_rgy_get_codesets
3.86 – rpc_ns_mgmt_set_exp_age
NAME
rpc_ns_mgmt_set_exp_age - Modifies the application's global expiration
age for local copies of name service data
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_mgmt_set_exp_age( unsigned32 expiration_age,
unsigned32 *status );
PARAMETERS
Input
expiration_age
An integer value that specifies the default expiration age, in
seconds, for local name service data. This expiration age applies
to all RPC name service interface (NSI) read operations (all the
next operations). An expiration age of 0 (zero) causes an
immediate update of the local name service data. To reset the
expiration age to an RPC-assigned random value between 8 and 12
hours, specify a value of rpc_c_ns_default_exp_age.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status code and its meaning is as follows:
rpc_s_ok Success.
DESCRIPTION
The rpc_ns_mgmt_set_exp_age() routine modifies the global expiration
age that the application is using. The expiration_age parameter
represents the amount of time, in seconds, that a local copy of data
from a name service attribute can exist before a request from the
application for the attribute requires updating the local copy. When
an application begins running, the RPC runtime specifies a random
value of between 8 and 12 hours as the default expiration age. The
default is global to the application.
Normally, you should avoid using this routine; instead, rely on the
default expiration age.
The RPC NSI next operations, which read data from name service
attributes, use an expiration age. A next operation normally starts
by looking for a local copy of the attribute data that an application
requests. In the absence of a local copy, the next operation creates
one with fresh attribute data from the name service database. If a
local copy already exists, the operation compares its actual age to
the expiration age being used by the application. If the actual age
exceeds the expiration age, the operation automatically tries to
update the local copy with fresh attribute data from the name service
database. If updating is impossible, the old local data remains in
place and the next operation fails, returning the
rpc_s_name_service_unavailable status code.
Permissions Required
No permissions are required.
CAUTIONS
Use this routine with extreme caution.
Setting the expiration age to a small value causes the RPC NSI next
operations to frequently update local data for any name service
attribute that your application requests. For example, setting the
expiration age to 0 (zero) forces all next operations to update local
data for the name service attribute that your application has
requested. Therefore, setting small expiration ages can create
performance problems for your application. Also, if your application
is using a remote server with the name service database, a small
expiration age can adversely affect network performance for all
applications.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_mgmt_handle_set_exp_age
rpc_ns_mgmt_set_exp_age
3.87 – rpc_ns_profile_delete
NAME
rpc_ns_profile_delete - Deletes a profile attribute
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_profile_delete( unsigned32 profile_name_syntax,
unsigned_char_t *profile_name,
unsigned32 *status );
PARAMETERS
Input
profile_name_syntax
An integer value that specifies the syntax of the
profile_name parameter. To use the syntax specified in
the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
profile_name
Specifies the name of the profile to delete. This can be either
the global or cell-relative name.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_profile_delete() routine deletes the profile attribute from
the specified entry in the name service database (the profile_name
parameter).
Neither the specified entry nor the entry names included as members in
each profile element are deleted.
Use this routine cautiously; deleting a profile may break a hierarchy
of profiles.
Permissions Required
You need write permission to the CDS object entry (the target profile
entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_profile_elt_add
rpc_ns_profile_elt_remove
3.88 – rpc_ns_profile_elt_add
NAME
rpc_ns_profile_elt_add - Adds an element to a profile; if necessary,
creates the entry
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_profile_elt_add( unsigned32 profile_name_syntax,
unsigned_char_t *profile_name,
rpc_if_id_t *if_id,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
unsigned32 priority,
unsigned_char_t *annotation,
unsigned32 *status );
PARAMETERS
Input
profile_name_syntax
An integer value that specifies the syntax of the
profile_name parameter. To use the syntax specified
in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
profile_name
Specifies the RPC profile that receives a new element. This can
be either the global or cell-relative name.
if_id
Specifies the interface identifier of the new profile element.
To add or replace the default profile element, specify NULL.
member_name_syntax
An integer value that specifies the syntax of
member_name. To use the syntax specified in the
RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
member_name
Specifies the entry in the name service database to include in
the new profile element. This can be either the global or cell-
relative name.
priority
An integer value (0 to 7) that specifies the relative priority
for using the new profile element during the import and lookup
operations. A value of 0 (zero) is the highest priority. A
value of 7 is the lowest priority. Two or more elements can have
the same priority. When adding the default profile member, use
a value of 0 (zero).
annotation
Specifies an annotation string that is stored as part of the new
profile element. The string can be up to 17 characters long.
Specify NULL or the string \0 if there is no annotation string.
The string is used by applications for informational purposes
only. For example, an application can use this string to store
the interface name string (specified in the IDL file).
DCE RPC does not use this string during lookup or import
operations, or for enumerating profile elements.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_class_version_mismatch
RPC class version mismatch.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_invalid_priority
Invalid profile element priority.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_profile_elt_add() routine adds an element to the profile
attribute of the entry in the name service database specified by the
profile_name parameter.
If the profile_name entry does not exist, this routine creates the
entry with a profile attribute and adds the profile element specified
by the if_id, member_name, priority, and annotation parameters. In
this case, the application must have permission to create the entry.
Otherwise, a management application with the necessary permissions
creates the entry by calling rpc_ns_mgmt_entry_create() before the
application is run.
If an element with the specified member name and interface identifier
are already in the profile, this routine updates the element's
priority and annotation string using the values provided in the
priority and annotation parameters.
An application can add the entry in the member_name parameter to a
profile before it creates the entry itself.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target profile entry). If the entry does not exist, you
also need insert permission to the parent directory.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_if_inq_id
rpc_ns_mgmt_entry_create
rpc_ns_profile_elt_remove
3.89 – rpc_ns_profile_elt_inq_begin
NAME
rpc_ns_profile_elt_inq_begin - Creates an inquiry context for
viewing the elements in a profile
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_profile_elt_inq_begin( unsigned32 profile_name_syntax,
unsigned_char_t *profile_name,
unsigned32 inquiry_type,
rpc_if_id_t *if_id,
unsigned32 vers_option,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
rpc_ns_handle_t *inquiry_context,
unsigned32 *status );
PARAMETERS
Input
profile_name_syntax
An integer value that specifies the syntax of the
profile_name parameter. To use the syntax specified
in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
profile_name
Specifies the name of the profile to view. This can be either
the global or cell-relative name.
inquiry_type
An integer value that specifies the type of inquiry to perform
on the profile. The following table describes the valid inquiry
types:
Valid Values of inquiry_type
_____________________________________________________________________
Value Description
_____________________________________________________________________
rpc_c_profile_default_elt Searches the profile for the
default profile element, if any.
The if_id, vers_option, and
member_name parameters are ignored.
rpc_c_profile_all_elts Returns every element from the pro-
file. The if_id, vers_option, and
member_name parameters are ignored.
rpc_c_profile_match_by_if Searches the profile for those ele-
ments that contain the interface
identifier specified by the if_id
and vers_option values. The
member_name parameter is ignored.
rpc_c_profile_match_by_mbr Searches the profile for those ele-
ments that contain the member name
specified by the member_name param-
eter. The if_id and vers_option
parameters are ignored.
rpc_c_profile_match_by_both Searches the profile for those ele-
ments that contain the interface
identifier and member name speci-
fied by the if_id, vers_option, and
member_name parameters.
if_id
Specifies the interface identifier of the profile elements to be
returned by rpc_ns_profile_elt_inq_next(). This parameter is used
only when specifying a value of either rpc_c_profile_match_by_if
or rpc_c_profile_match_by_both for the inquiry_type parameter.
Otherwise, this parameter is ignored and you can specify the value
NULL.
vers_option
Specifies how rpc_ns_profile_elt_inq_next() uses the if_id
parameter. This parameter is used only when specifying a value
of either rpc_c_profile_match_by_if or rpc_c_profile_match_by_both
for the inquiry_type parameter. Otherwise, this parameter is
ignored and you can specify the value 0 (zero).
The following table describes the valid values for this parameter:
Valid Values of vers_option
_____________________________________________________________________
Value Description
_____________________________________________________________________
rpc_c_vers_all Returns profile elements that offer
the specified interface UUID,
regardless of the version numbers.
For this value, specify 0 (zero)
for both the major and minor ver-
sions in if_id.
rpc_c_vers_compatible Returns profile elements that offer
the same major version of the
specified interface UUID and a
minor version greater than or equal
to the minor version of the speci-
fied interface UUID.
rpc_c_vers_exact Returns profile elements that offer
the specified version of the speci-
fied interface UUID.
rpc_c_vers_major_only Returns profile elements that offer
the same major version of the
specified interface UUID (ignores
the minor version). For this
value, specify 0 (zero) for the
minor version in if_id.
rpc_c_vers_upto Returns profile elements that offer
a version of the specified inter-
face UUID less than or equal to the
specified major and minor version.
(For example, if if_id contains
V2.0 and the profile contains ele-
ments with the versions V1.3, V2.0,
and V2.1,
rpc_ns_profile_elt_inq_next()
returns the elements with V1.3 and
V2.0.)
member_name_syntax
An integer value that specifies the syntax of the member_name
parameter in this routine and the syntax of the member_name
parameter in rpc_ns_profile_elt_inq_next(). To use the syntax
specified in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
member_name
Specifies the member name that rpc_ns_profile_elt_inq_next()
looks for in profile elements. This can be either the global
or cell-relative name. This parameter is used only when
specifying a value of either rpc_c_profile_match_by_mbr or
rpc_c_profile_match_by_both for the inquiry_type parameter.
Otherwise, this parameter is ignored and you specify the value
NULL.
Output
inquiry_context
Returns a name service handle for use with the
rpc_ns_profile_elt_inq_next() and rpc_ns_profile_elt_inq_done()
routines.
status
Returns the status code from this routine, indicating indicates
whether the routine completed successfully or, if not, why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_inquiry_type
Invalid inquiry type.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_invalid_vers_option
Invalid version option.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_profile_elt_inq_begin() routine creates an inquiry context
for viewing the elements in a profile.
Using the inquiry_type and vers_option parameters, an application
specifies which of the following profile elements will be returned
from calls to rpc_ns_profile_elt_inq_next():
+ The default element.
+ All elements.
+ Those elements with the specified interface identifier.
+ Those elements with the specified member name.
+ Those elements with both the specified interface identifier and
member name.
Before calling rpc_ns_profile_elt_inq_next(), the application must
first call this routine to create an inquiry context.
When finished viewing the profile elements, the application calls
the rpc_ns_profile_elt_inq_done() routine to delete the inquiry
context.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_if_inq_id
rpc_ns_mgmt_handle_set_exp_age
rpc_ns_profile_elt_inq_done
rpc_ns_profile_elt_inq_next
3.90 – rpc_ns_profile_elt_inq_done
NAME
rpc_ns_profile_elt_inq_done - Deletes the inquiry context for a
profile
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_profile_elt_inq_done( rpc_ns_handle_t *inquiry_context,
unsigned32 *status );
PARAMETERS
Input/Output
inquiry_context
Specifies the name service handle to delete. (A name service
handle is created by calling rpc_ns_profile_elt_inq_begin().)
Returns the value NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_ns_handle Invalid name service handle.
DESCRIPTION
The rpc_ns_profile_elt_inq_done() routine deletes an inquiry context
created by calling rpc_ns_profile_elt_inq_begin().
An application calls this routine after viewing profile elements
using the rpc_ns_profile_elt_inq_next() routine.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_profile_elt_inq_begin
rpc_ns_profile_elt_inq_next
3.91 – rpc_ns_profile_elt_inq_next
NAME
rpc_ns_profile_elt_inq_next - Returns one element at a time from
a profile
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_profile_elt_inq_next( rpc_ns_handle_t inquiry_context,
rpc_if_id_t *if_id,
unsigned_char_t **member_name,
unsigned32 *priority,
unsigned_char_t **annotation,
unsigned32 *status );
PARAMETERS
Input
inquiry_context
Specifies a name service handle. This handle is returned from
the rpc_ns_profile_elt_inq_begin() routine.
Output
if_id
Returns the interface identifier of the profile element.
member_name
Returns a pointer to the profile element's member name. The name
is a global name. The syntax of the returned name is specified by
the member_name_syntax parameter in
rpc_ns_profile_elt_inq_begin(). Specify NULL to prevent the
routine from returning this parameter. In this case the
application does not call rpc_string_free().
priority
Returns the profile element priority.
annotation
Returns the annotation string for the profile element. If there
is no annotation string in the profile element, the string \0 is
returned. Specify NULL to prevent the routine from returning
this parameter. In this case the application does not need to
call the rpc_string_free() routine.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_class_version_mismatch
RPC class version mismatch.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_ns_handle
Invalid name service handle.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_more_elements
No more elements.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_not_rpc_entry
Not an RPC entry.
DESCRIPTION
The rpc_ns_profile_elt_inq_next() routine returns one element from
the profile specified by the profile_name parameter in the
rpc_ns_profile_elt_inq_begin() routine.
The selection criteria for the element returned are based on the
inquiry_type parameter in the rpc_ns_profile_elt_inq_begin() routine.
The rpc_ns_profile_elt_inq_next() routine returns all the components
(interface identifier, member name, priority, annotation string) of
a profile element.
An application can view all the selected profile entries by
repeatedly calling the rpc_ns_profile_elt_inq_next() routine.
When all the elements have been viewed, this routine returns an
rpc_s_no_more_elements status code. The returned elements are
unordered.
On each call to this routine that returns a profile element, the
DCE RPC runtime allocates memory for the returned member_name (which
points to a global name) and annotation strings. The application is
responsible for calling the rpc_string_free() routine for each
returned member_name and annotation string.
After viewing the profile's elements, the application must call the
rpc_ns_profile_elt_inq_done() routine to delete the inquiry context.
Permissions Required
You need read permission to the CDS object entry (the target profile
entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_profile_elt_begin
rpc_ns_profile_elt_done
rpc_string_free
3.92 – rpc_ns_profile_elt_remove
NAME
rpc_ns_profile_elt_remove - Removes an element from a profile
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ns_profile_elt_remove( unsigned32 profile_name_syntax,
unsigned_char_t *profile_name,
rpc_if_id_t *if_id,
unsigned32 member_name_syntax,
unsigned_char_t *member_name,
unsigned32 *status );
PARAMETERS
Input
profile_name_syntax
An integer value that specifies the syntax of the
profile_name parameter. To use the syntax specified
in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
rpc_c_ns_syntax_default.
profile_name
Specifies the profile from which to remove an element. This
can be either the global or cell-relative name.
if_id
Specifies the interface identifier of the profile element to be
removed. Specify NULL to remove the default profile member.
member_name_syntax
An integer value that specifies the syntax of member_name. To
use the syntax specified in the RPC_DEFAULT_ENTRY_SYNTAX logical
name, provide rpc_c_ns_syntax_default.
member_name
Specifies the name service entry name in the profile element to
remove. This can be either the global or cell-relative name.
When if_id is NULL, this argument is ignored.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_entry_not_found
Name service entry not found.
rpc_s_incomplete_name
Incomplete name.
rpc_s_invalid_name_syntax
Invalid name syntax.
rpc_s_name_service_unavailable
Name service unavailable.
rpc_s_no_ns_permission
No permission for name service operation.
rpc_s_profile_element_not_found
Profile element not found.
rpc_s_unsupported_name_syntax
Unsupported name syntax.
DESCRIPTION
The rpc_ns_profile_elt_remove() routine removes a profile element
from the profile specified by profile_name. Unless if_id is NULL,
the member_name parameter and the if_id parameter must match the
corresponding profile element attributes exactly for an element to
be removed. When if_id is NULL, the default profile element is
removed, and the member_name argument is ignored.
The routine removes the reference to the entry specified by
member_name from the profile; it does not delete the entry itself.
Use this routine cautiously; removing elements from a profile may
break a hierarchy of profiles.
Permissions Required
You need both read permission and write permission to the CDS object
entry (the target profile entry).
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ns_profile_delete
rpc_ns_profile_elt_add
3.93 – rpc_object_inq_type
NAME
rpc_object_inq_type - Returns the type of an object
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_object_inq_type( uuid_t *obj_uuid,
uuid_t *type_uuid,
unsigned32 *status );
PARAMETERS
Input
obj_uuid
Specifies the object UUID whose associated type UUID is returned.
Supply NULL to specify a nil UUID for this parameter.
Output
type_uuid
Returns the type UUID corresponding to the object UUID supplied
in the obj_uuid parameter. Specifying NULL here prevents the
return of a type UUID. An application, by specifying NULL here,
can determine from the value returned in status whether obj_uuid
is registered. This determination occurs without the application
specifying an output type UUID variable.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_object_not_found Object not found.
uuid_s_bad_version Bad UUID version.
DESCRIPTION
A server application calls the rpc_object_inq_type() routine to obtain
the type UUID of an object.
If the object is registered with the RPC runtime using the
rpc_object_set_type() routine, the registered type is returned.
Optionally, an application can maintain an object/type registration
privately. In this case, if the application provides an object
inquiry function (see the rpc_object_set_inq_fn reference page), the
RPC runtime uses that function to determine an object's type.
The table below shows how rpc_object_inq_type() obtains the returned
type UUID.
Rules for Returning an Object's Type
_____________________________________________________________________
Was object UUID Was an object inquiry
registered (using function registered(using
rpc_object_set_type)? rpc_object_set_inq_fn)? Return Value
_____________________________________________________________________
Yes Ignored Returns the object's
registered type UUID.
No Yes Returns the type UUID
returned from calling
the inquiry function.
No No Returns the nil UUID.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_object_set_inq_fn
rpc_object_set_type
3.94 – rpc_object_set_inq_fn
NAME
rpc_object_set_inq_fn - Registers an object inquiry function
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_object_set_inq_fn( rpc_object_inq_fn_t inquiry_fn,
unsigned32 *status );
PARAMETERS
Input
inquiry_fn
Specifies a pointer to an object type inquiry function. When an
application calls the rpc_object_inq_type() routine and the RPC
runtime finds that the specified object is not registered, the
runtime automatically calls the rpc_object_inq_type() routine to
determine the object's type. Specify NULL to remove a previously
set inquiry function.
The following C language definition for rpc_object_inq_fn_t
illustrates the prototype for this function:
typedef void (*rpc_object_inq_fn_t)
(
uuid_t *object_uuid, /* in */
uuid_t *type_uuid, /* out */
unsigned32 *status /* out */
);
The returned type_uuid and status values are returned as the
output arguments from the rpc_object_inq_type() routine.
If you specify NULL, the rpc_object_set_inq_fn() routine
unregisters (that is, removes) a previously registered object
type inquiry function.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status code and its meaning is as
follows:
rpc_s_ok Success.
DESCRIPTION
A server application calls rpc_object_set_inq_fn() to specify a
function to determine an object's type. If an application privately
maintains object/type registrations, the specified inquiry function
returns the type UUID of an object from that registration.
The RPC runtime automatically calls the inquiry function when the
application calls rpc_object_inq_type() and the object was not
previously registered by rpc_object_set_type(). The RPC runtime
also automatically calls the inquiry function for every remote
procedure call it receives if the object was not previously
registered.
Cautions
Use this routine with caution. When the RPC runtime automatically
calls this routine in response to a received remote procedure call,
the inquiry function can be called from the context of runtime
internal threads with runtime internal locks held. The inquiry
function should not block or at least not block for long (for example,
the inquiry function should not perform a remote procedure call).
Also, the inquiry function must not unwind because of an exception.
In general, the inquiry function should not call back into the RPC
runtime. It is legal to call rpc_object_set_type() or any of the
uuid_* routines. Failure to comply with these restrictions will
result in undefined behavior.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_object_inq_type
rpc_object_set_type
3.95 – rpc_object_set_type
NAME
rpc_object_set_type - Registers the type of an object with the RPC
runtime
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_object_set_type( uuid_t *obj_uuid,
uuid_t *type_uuid,
unsigned32 *status );
PARAMETERS
Input
obj_uuid
Specifies an object UUID to associate with the type UUID in the
type_uuid parameter. Do not specify NULL or a nil UUID.
type_uuid
Specifies the type UUID of the obj_uuid parameter. Specify
an argument value of NULL or a nil UUID to reset the object
type to the default association of object UUID/nil type UUID.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_already_registered Object already registered.
rpc_s_invalid_object Invalid object.
uuid_s_bad_version Bad UUID version.
DESCRIPTION
The rpc_object_set_type() routine assigns a type UUID to an object
UUID.
By default, the RPC runtime assumes that the type of all objects
is nil. A server program that contains one implementation of an
interface (one manager entry point vector) does not need to call
this routine, provided that the server registered the interface with
the nil type UUID (see the rpc_server_register_if reference page).
A server program that contains multiple implementations of an
interface (multiple manager entry point vectors; that is, multiple
type UUIDs) calls this routine once for each object UUID the server
offers. Associating each object with a type UUID tells the RPC
runtime which manager entry point vector (interface implementation)
to use when the server receives a remote procedure call for a non-nil
object UUID.
The RPC runtime allows an application to set the type for an
unlimited number of objects.
To remove the association between an object UUID and its type UUID
(established by calling this routine), a server calls this routine
again and specifies the value NULL or a nil UUID for the type_uuid
parameter. This resets the association between an object UUID and
type UUID to the default.
A server cannot register a nil object UUID. The RPC runtime
automatically registers the nil object UUID with a nil type UUID.
Attempting to set the type of a nil object UUID will result in the
routine's returning the status code rpc_s_invalid_object.
Servers that want to maintain their own object UUID to type UUID
mapping can use rpc_object_set_inq_fn() in place of, or in addition
to, rpc_object_set_type().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_object_set_inq_fn
rpc_server_register_if
3.96 – rpc_protseq_vector_free
NAME
rpc_protseq_vector_free - Frees the memory used by a vector and its
protocol sequences
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_protseq_vector_free( rpc_protseq_vector_t **protseq_vector,
unsigned32 *status );
PARAMETERS
Input/Output
protseq_vector
Specifies the address of a pointer to a vector of protocol
sequences. On return the pointer is set to NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status code and its meaning is as follows:
rpc_s_ok Success.
DESCRIPTION
The rpc_protseq_vector_free() routine frees the memory used to store
a vector of protocol sequences. The freed memory includes both the
protocol sequences and the vector itself.
Call rpc_network_inq_protseqs() to obtain a vector of protocol
sequences. Follow a call to rpc_network_inq_protseqs() with a call
to rpc_protseq_vector_free().
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_network_inq_protseqs
3.97 – rpc_rgy_get_codesets
NAME
rpc_rgy_get_codesets - Gets supported code sets information from the
local host
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_rgy_get_codesets( rpc_codeset_mgmt_p_t *code_sets_array,
error_status_t *status );
PARAMETERS
Input
No input is required.
Output
code_sets_array
An integer array that specifies the code sets that the client's
or server's host environment supports. Each array element is an
integer value that uniquely identifies one code set.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
rpc_s_ok
rpc_s_no_memory
DESCRIPTION
The rpc_rgy_get_codesets() routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment.
The rpc_rgy_get_codesets() routine examines the locale environment of
the host on which the client or server process is running to determine
the local code set currently in use by the client or server process
and the set of supported code set conversion routines that exist on
the host into which the client or server process can convert if
necessary. It then reads the code sets registry on the local host to
retrieve the unique identifiers associated with these supported code
sets.
The routine returns a code sets array. The set of values returned in
this structure correspond to the process's local code set and the code
sets into which processes that run on this host can convert. The
array also contains, for each code set, the maximum number of bytes
that code set uses to encode one character (c_max_bytes).
Server applications use the rpc_rgy_get_codesets() routine in their
initialization code to get their host's supported character and code
sets values in order to export them into the name service database
with rpc_ns_mgmt_set_attribute().
Client applications use the rpc_rgy_get_codesets() routine during the
server binding selection process to retrieve the supported character
and code sets at their host in order to evaluate them against the
character and code sets that a server supports. Client applications
that use the evaluation routines rpc_cs_eval_with_universal() and
rpc_cs_eval_without_universal() do not need to call this routine
explicitly, because these code sets evaluation routines call it on
the client's behalf. Application developers who are writing their
own character and code set evaluation routines may need to include
rpc_rgy_get_codesets() in their user-written evaluation routines.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Commands: csrc(8dce).
Functions: rpc_ns_mgmt_read_codesets
rpc_ns_mgmt_remove_attribute
rpc_ns_mgmt_set_attribute
3.98 – rpc_rgy_get_max_bytes
NAME
rpc_rgy_get_max_bytes - Gets the maximum number of bytes that a
code set uses to encode one character from
the code set registry on a host
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_rgy_get_max_bytes( unsigned32 rgy_code_set_value,
unsigned16 *rgy_max_bytes,
error_status_t *status );
PARAMETERS
Input
rgy_code_set_value
The registered hexadecimal value that uniquely identifies the
code set.
Output
rgy_max_bytes
The registered decimal value that indicates the number of bytes
this code set uses to encode one character.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
dce_cs_c_cannot_open_file
dce_cs_c_cannot_read_file
dce_cs_c_notfound
dce_cs_c_unknown
rpc_s_ok
DESCRIPTION
The rpc_rgy_get_max_bytes() routine belongs to a set of DCE RPC
routines for use by client and server applications that are
transferring international character data in a heterogeneous
character set and code sets environment.
The rpc_rgy_get_max_bytes() routine reads the code set registry on the
local host. It takes the specified registered code set value, uses it
as an index into the registry, and returns the decimal value that
indicates the number of bytes that the code set uses to encode one
character.
The DCE RPC stub support routines for buffer sizing use the
rpc_rgy_get_max_bytes() routine as part of their procedure to
determine whether additional storage needs to be allocated for
conversion between local and network code sets. The DCE RPC stub
support routines call the rpc_rgy_get_max_bytes() routine once to
get the rgy_max_bytes value for the code set to be used to transfer
the data over the network (the "network" code set) then call the
routine again to get the rgy_max_bytes value of their local code set.
The stubs then compare the two values to determine whether or not
additional buffers are necessary or whether the conversion can be
done "in place".
Client and server applications that use the DCE RPC buffer sizing
routines byte_net_size(), byte_local_size(), wchar_t_net_size(), and
wchar_t_local_size() do not need to call this routine explicitly
because these DCE RPC stub support routines call it on their behalf.
Application programmers who are developing their own stub support
routines for buffer sizing can use the rpc_rgy_get_max_bytes() routine
in their code to get code set max_byte information for their user-
written buffer sizing routines.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Commands: csrc.
Functions: dce_cs_loc_to_rgy
dce_cs_rgy_to_loc
rpc_ns_mgmt_read_code_sets
rpc_rgy_get_code_sets
3.99 – rpc_server_inq_bindings
NAME
rpc_server_inq_bindings - Returns binding handles for communications
with a server
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_inq_bindings( rpc_binding_vector_t **binding_vector,
unsigned32 *status );
PARAMETERS
Input
None.
Output
binding_vector
Returns the address of a vector of server binding handles.
status Returns the status code from this routine. This status
code indicates whether the routine completed successfully
or, if not, why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_no_bindings No bindings.
DESCRIPTION
The rpc_server_inq_bindings() routine obtains a vector of server
binding handles. Binding handles are created by the RPC runtime
when a server application calls any of the following routines to
register protocol sequences:
+ 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()
The returned binding vector can contain binding handles with dynamic
endpoints and binding handles with well-known endpoints, depending on
which of the preceding routines the server application called. The
rpc_intro reference page contains an explanation of dynamic and well-
known endpoints.
A server uses the vector of binding handles for exporting to the name
service, for registering with the local endpoint map, or for
conversion to string bindings.
If there are no binding handles (no registered protocol sequences),
this routine returns the rpc_s_no_bindings status code and returns
the value NULL to the binding_vector parameter.
The server is responsible for calling the rpc_binding_vector_free()
routine to deallocate the memory used by the vector.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
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
3.100 – rpc_server_inq_if
NAME
rpc_server_inq_if - Returns the manager entry point vector registered
for an interface
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_inq_if( rpc_if_handle_t if_handle,
uuid_t *mgr_type_uuid,
rpc_mgr_epv_t *mgr_epv,
unsigned32 *status );
PARAMETERS
Input
if_handle
Specifies the interface specification whose manager Entry Point
Vector (EPV) pointer is returned in the mgr_epv parameter.
mgr_type_uuid
Specifies a type UUID for the manager whose EPV pointer is
returned in the mgr_epv parameter. Specifying the value NULL
(or a nil UUID) has this routine return a pointer to the manager
EPV that is registered with if_handle and the nil type UUID of
the manager.
Output
mgr_epv
Returns a pointer to the manager EPV corresponding to if_handle
and mgr_type_uuid.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_unknown_if Unknown interface.
rpc_s_unknown_mgr_type Unknown manager type.
DESCRIPTION
A server application calls the rpc_server_inq_if() routine to
determine the manager EPV for a registered interface and type UUID
of the manager.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_server_register_if
3.101 – rpc_server_listen
NAME
rpc_server_listen - Tells the RPC runtime to listen for remote
procedure calls
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_listen( unsigned32 max_calls_exec,
unsigned32 *status );
PARAMETERS
Input
max_calls_exec
Specifies the maximum number of concurrent executing remote
procedure calls. Use the value rpc_c_listen_max_calls_default
to specify the default value.
Also, the five rpc_server_use_*protseq* routines limit (according
to their max_call_requests parameter) the number of concurrent
remote procedure call requests that a server can accept.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_already_listening
Server already listening.
rpc_s_max_calls_too_small
Maximum calls value too small.
rpc_s_no_protseqs_registered
No protocol sequences registered.
DESCRIPTION
The rpc_server_listen() routine makes a server listen for remote
procedure calls. DCE RPC allows a server to simultaneously process
multiple calls. The max_calls_exec parameter specifies the maximum
number of concurrent remote procedure calls the server executes.
Each remote procedure call executes in a call execution thread.
The implementation of the RPC architecture determines whether it
reuses call execution threads for the execution of subsequent remote
procedure calls or, instead, it creates a new thread for each
execution of a subsequent remote procedure call.
The following conditions affect the number of concurrent remote
procedure calls that a server can process:
+ Sufficient network resources must be available to accept
simultaneous call requests arriving over a particular protocol
sequence. The value of max_call_requests in the five
rpc_server_use_*protseq* routines advises the RPC runtime about
the runtime's request of network resources.
+ Enough call threads must be available to execute the simultaneous
call requests once they have been accepted. The value of
max_calls_exec in rpc_server_listen() specifies the number of
call threads.
These conditions are independent of each other.
A server application that specifies a value for max_calls_exec greater
than 1 is responsible for concurrency control among the remote
procedures since each executes in a separate thread.
If the server receives more remote procedure calls than it can execute
(more calls than the value of max_calls_exec), the RPC runtime accepts
and queues additional remote procedure calls until a call execution
thread is available. From the client's perspective, a queued remote
procedure call appears the same as one that the server is actively
executing. A client call remains blocked and in the queue until any
one of the following events occurs:
+ The remote procedure call is assigned to an available call
execution thread and the call runs to completion.
+ The client no longer can communicate with the server.
+ The client thread is canceled and the remote procedure call does
not complete within the cancel time-out limits.
The implementation of the RPC architecture determines the amount of
queuing it provides.
The RPC runtime continues listening for remote procedure calls (that
is, the routine does not return to the server) until one of the
following events occurs:
+ One of the server application's manager routines calls
rpc_mgmt_stop_server_listening().
+ A client is allowed to, and makes, a remote
rpc_mgmt_stop_server_listening() call to the server.
On receiving a request to stop listening, the RPC runtime stops
accepting new remote procedure calls for all registered interfaces.
Executing calls and existing queued calls are allowed to complete.
After all calls complete, rpc_server_listen() returns to the caller,
which is a server application.
For more information about a server's listening for and handling
incoming remote procedure calls, refer to the OSF DCE Application
Development Guide. It also contains information about canceled
threads.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_mgmt_server_stop_listening
rpc_server_register_if
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
Books: OSF DCE Application Development Guide.
3.102 – rpc_server_register_auth_info
NAME
rpc_server_register_auth_info - Registers authentication information
with the RPC runtime
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_register_auth_info(
unsigned_char_t *server_princ_name,
unsigned32 authn_svc,
rpc_auth_key_retrieval_fn_t get_key_fn,
void *arg,
unsigned32 *status );
PARAMETERS
Input
server_princ_name
Specifies the principal name to use for the server when
authenticating remote procedure calls using the service
specified by authn_svc. The content of the name and its
syntax is defined by the authentication service in use.
authn_svc
Specifies the authentication service to use when the server
receives a remote procedure call request. The following
authentication services are supported:
rpc_c_authn_none
No authentication.
rpc_c_authn_dce_secret
DCE shared-secret key authentication.
rpc_c_authn_winnt
Microsoft NT Lan Manager authentication.
rpc_c_authn_dce_public
DCE public key authentication (reserved for future
use).
rpc_c_authn_default
DCE default authentication service.
get_key_fn
Specifies the address of a server-provided routine that returns
encryption keys.
The following C definition for rpc_auth_key_retrieval_fn_t
illustrates the prototype for the encryption key acquisition
routine:
typedef void (*rpc_auth_key_retrieval_fn_t)
(
void *arg, /* in */
unsigned_char_t *server_princ_name, /* in */
unsigned32 key_type, /* in */
unsigned32 key_ver, /* in */
void **key, /* out */
unsigned32 *status /* out */
);
The RPC runtime passes the server_princ_name parameter value
specified on the call to rpc_server_register_auth_info(), as
the server_princ_name parameter value, to the get_key_fn key
acquisition routine. The RPC runtime automatically provides a
value for the key version (key_ver) parameter. For a key_ver
value of 0 (zero), the key acquisition routine must return the
most recent key available. The routine returns the key in the
key parameter. The key_type parameter specifies a Kerberos
encryption key type. Because currently the DCE supports only
DES encryption, this parameter can be ignored.
If the key acquisition routine, when called from the
rpc_server_register_auth_info() routine, returns a status other
than rpc_s_ok, the rpc_server_register_auth_info() routine fails
and returns the error status to the calling server.
If the key acquisition routine, when called by the RPC runtime
while authenticating a client remote procedure call request,
returns a status other than rpc_s_ok, the request fails and the
RPC runtime returns the error status to the client.
arg Specifies an argument to pass to the get_key_fn key acquisition
routine, if specified. (See the description of the get_key_fn
parameter for details.)
Specify NULL for arg to use the default key table file,
DCE$LOCAL:[KRB]v5srvtab.;
The calling server must be privileged to access this file.
If arg is a key table file name, the file must have been
created with the ktadd command. If the specified key table
file resides in DCE$LOCAL:[KRB5], you can supply only the file
name. If the file does not reside in DCE$LOCAL:[KRB5], you must
supply the full pathname. You must prepend the file's absolute
pathname with the prefix FILE:.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_unknown_authn_service
Unknown authentication service.
rpc_s_key_func_not_allowed
authn_svc is rpc_c_authn_default and a non-null
value was supplied for get_key_fn parameter.
DESCRIPTION
The rpc_server_register_auth_info() routine registers an authenti-
cation service to use for authenticating remote procedure calls
to a particular server principal. A server calls this routine once
for each authentication service and principal name combination that
it wants to register.
The authentication service specified by a client (using the
rpc_binding_set_auth_info() routine) must be one of the authentication
services registered by the server. If it is not, the client's remote
procedure call request fails with an rpc_s_unknown_authn_service
status code.
The following table shows the RPC runtime behavior for acquiring
encryption keys for each supported authentication service. Note that
if authn_svc is rpc_c_authn_default, then get_key_fn must be NULL.
RPC Key Acquisition for Authentication Services
_______________________________________________________________________
authn_svc get_key_fn arg Runtime Behavior
_______________________________________________________________________
rpc_c_authn_default NULL NULL Uses the default method of
encryption key acquisition
from the default key
table.
_______________________________________________________________________
rpc_c_authn_default NULL non-NULL Uses the default method of
encryption key acquisition
from the specified key
table.
_______________________________________________________________________
rpc_c_authn_default non-NULL Ignored Error returned.
_______________________________________________________________________
rpc_c_authn_none Ignored Ignored No authentication
performed.
_______________________________________________________________________
rpc_c_authn_dce_secret NULL NULL Uses the default method of
encryption key acquisition
from the default key table.
_______________________________________________________________________
rpc_c_authn_dce_secret NULL non-NULL Uses the default method of
encryption key acquisition
from the specified key
table.
_______________________________________________________________________
rpc_c_authn_dce_secret non-NULL NULL Uses the specified encryp-
tion key acquisition
routine to obtain keys
from the default key table.
_______________________________________________________________________
rpc_c_authn_dce_secret non-NULL non-NULL Uses the specified encryp-
tion key acquisition
routine to obtain keys from
the specified key table.
_______________________________________________________________________
rpc_c_authn_winnt Ignored Ignored Uses the default method of
encryption key acquisition
from the default key table.
_______________________________________________________________________
rpc_c_authn_dce_public Ignored Ignored (Reserved for future use.)
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_set_auth_info
3.103 – rpc_server_register_if
NAME
rpc_server_register_if - Registers an interface with the RPC runtime
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_register_if( rpc_if_handle_t if_handle,
uuid_t *mgr_type_uuid,
rpc_mgr_epv_t mgr_epv,
unsigned32 *status );
PARAMETERS
Input
if_handle
An IDL-generated data structure specifying the interface to
register.
mgr_type_uuid
Specifies a type UUID to associate with the mgr_epv parameter.
Specifying the value NULL (or a nil UUID) registers the
if_handle with a nil type UUID.
mgr_epv
Specifies the manager routines' entry point vector. To use the
IDL-generated default entry point vector, specify NULL.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_type_already_registered
An interface with the given type of UUID is already
registered.
DESCRIPTION
The rpc_server_register_if() routine registers a server interface
with the RPC runtime. A server can register an unlimited number of
interfaces. Once registered, an interface is available to clients
through any binding handle of the server, provided that the binding
handle is compatible for the client.
A server must provide the following information to register an
interface:
+ An interface specification, which is a data structure generated
by the IDL compiler. The server specifies the interface
specification of the interface using the if_handle parameter.
+ A type UUID and manager Entry Point Vector (EPV), a data pair
that determines which manager routine executes when a server
receives a remote procedure call request from a client.
The server specifies the type UUID and EPV using the
mgr_type_uuid and mgr_epv parameters, respectively. Note that
when a non-nil type UUID is specified, the server must also call
the rpc_object_set_type() routine to register objects of this
non-nil type.
A server that only offers a single manager for an interface calls
rpc_server_register_if() once for that interface. In the simple case
where the single manager's entry point names are the same as the
operation names in the IDL interface definition, the IDL-generated
default manager EPV for the interface may be used. The value NULL in
mgr_epv specifies the default manager EPV.
Note that if a server offers multiple implementations of an interface,
the server code must register a separate manager entry point vector
for each interface implementation.
Rules for Invoking Manager Routines
The RPC runtime dispatches an incoming remote procedure call to a
manager that offers the requested RPC interface. When multiple
managers are registered for an interface, the RPC runtime must
select one of them. To select a manager, the RPC runtime uses the
object UUID specified by the call's binding handle.
The following table summarizes the rules applied for invoking manager
routines.
Rules for Invoking Manager Routines
_______________________________________________________________________
Object Has Server Has Server
UUID Set Type of Set Type for
of Call¹ Object UUID?² Manager EPV³ Dispatching Action
_______________________________________________________________________
Nil Not applicable(4) Yes Uses the manager with the nil type
UUID.
Nil Not applicable(4) No Error (rpc_s_unknown_mgr_type). Rejects
the remote procedure call.
Non-nil Yes Yes Uses the manager with the same type
UUID.
Non-nil No Ignored Uses the manager with the nil type
UUID. If no manager with the nil
type UUID, error
(rpc_s_unknown_mgr_type). Rejects
the remote procedure call.
Non-nil Yes No Error (rpc_s_unknown_mgr_type). Rejects
the remote procedure call.
¹ This is the object UUID found in a binding handle for a remote
procedure.
² By calling rpc_object_set_type() to specify the type UUID for an
object.
³ By calling rpc_server_register_if() using the same type UUID.
4 The nil object UUID is always automatically assigned the nil
type UUID. It is illegal to specify a nil object UUID in
rpc_object_set_type().
For more information about registering server interfaces and invoking
manager routines, refer to the OSF DCE Application Development Guide.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_set_object
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_object_set_type
rpc_server_unregister_if
Books: OSF DCE Application Development Guide.
3.104 – rpc_server_unregister_if
NAME
rpc_server_unregister_if - Removes an interface from the RPC runtime
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_unregister_if( rpc_if_handle_t if_handle,
uuid_t *mgr_type_uuid,
unsigned32 *status );
PARAMETERS
Input
if_handle
Specifies an interface specification to unregister (remove).
Specify NULL to remove all interfaces previously registered with
the type UUID value given in the mgr_type_uuid parameter.
mgr_type_uuid
Specifies the type UUID for the manager Entry Point Vector (EPV)
to remove. This needs to be the same value as provided in a call
to the rpc_server_register_if() routine.
Specify NULL to remove the interface given in the if_handle
parameter for all previously registered type UUIDs.
Specify a nil UUID to remove the IDL-generated default manager
EPV. In this case all manager EPVs registered with a non-nil
type UUID remain registered.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_unknown_if Unknown interface.
rpc_s_unknown_mgr_type Unknown manager type.
DESCRIPTION
The rpc_server_unregister_if() routine removes the association between
an interface and a manager Entry Point Vector (EPV).
Specify the manager EPV to remove by providing, in the mgr_type_uuid
parameter, the type UUID value specified in a call to the
rpc_server_register_if() routine. Once removed, an interface is no
longer available to client applications.
When an interface is removed, the RPC runtime stops accepting new
calls for that interface. Executing calls (on that interface) are
allowed to complete.
The table below summarizes the actions of this routine.
Rules for Removing an Interface
_____________________________________________________________________
if_handle mgr_type_uuid Action
_____________________________________________________________________
non-NULL non-NULL Removes the manager EPV associated
with the specified parameters.
non-NULL NULL Removes all manager EPVs associated
with parameter if_handle.
NULL non-NULL Removes all manager EPVs associated
with parameter mgr_type_uuid.
NULL NULL Removes all manager EPVs.
Note that when both of the parameters if_handle and mgr_type_uuid are
given the value NULL, this call has the effect of preventing the
server from receiving any new remote procedure calls since all the
manager EPVs for all interfaces have been removed.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_server_register_if
3.105 – rpc_server_use_all_protseqs
NAME
rpc_server_use_all_protseqs - Tells the RPC runtime to use all
supported protocol sequences for
receiving remote procedure calls
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_use_all_protseqs( unsigned32 max_call_requests,
unsigned32 *status );
PARAMETERS
Input
max_call_requests
Specifies the maximum number of concurrent remote procedure call
requests that the server can accept.
The RPC runtime guarantees that the server can accept at least
this number of concurrent call requests. The actual number of
these requests can be greater than the value of
max_call_requests and can vary for each protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify the
default parameter value.
Note that in this version of DCE RPC, any number you specify is
replaced by the default value.
Also, the rpc_server_listen() routine limits (according to its
max_calls_exec parameter) the amount of concurrent remote
procedure call execution. See the rpc_server_listen
reference page for more information.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
rpc_s_ok Success.
rpc_s_cant_create_socket
Cannot create socket.
rpc_s_max_descs_exceeded
Exceeded maximum number of network descriptors.
rpc_s_no_protseqs
No supported protocol sequences.
DESCRIPTION
The rpc_server_use_all_protseqs() routine registers all supported
protocol sequences with the RPC runtime. A server must register at
least one protocol sequence with the RPC runtime to receive remote
procedure call requests.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains a
dynamic endpoint that the RPC runtime and operating system generated.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
After registering protocol sequences, a server typically calls the
following routines:
rpc_server_inq_bindings()
Obtains a vector containing all of the server's binding
handles.
rpc_ep_register()
Registers the binding handles with the local endpoint
map.
rpc_ep_register_no_replace()
Registers the binding handles with the local endpoint
map.
rpc_ns_binding_export()
Places the binding handles in the name service database
for access by any client.
rpc_binding_vector_free()
Frees the vector of server binding handles.
rpc_server_register_if()
Registers with the RPC runtime those interfaces that the
server offers.
rpc_server_listen()
Enables the reception of remote procedure calls.
To register protocol sequences selectively, a server calls one of the
following routines:
rpc_server_use_protseq() rpc_server_use_all_protseqs_if()
rpc_server_use_protseq_if() rpc_server_use_protseq_ep()
For an explanation of how a server can establish a client/server
relationship without using the local endpoint map or the name service
database, see the information on string bindings in the rpc_intro
reference page.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_from_string_binding
rpc_binding_to_string_binding
rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
3.106 – rpc_server_use_all_protseqs_if
NAME
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
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_use_all_protseqs_if( unsigned32 max_call_requests,
rpc_if_handle_t if_handle,
unsigned32 *status );
PARAMETERS
Input
max_call_requests
Specifies the maximum number of concurrent remote procedure call
requests that the server can accept.
The RPC runtime guarantees that the server can accept at least
this number of concurrent call requests. The actual number of
these requests can be greater that the value of max_call_requests
and can vary for each protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify the
default parameter value.
Note that in this version of DCE RPC, any number you specify is
replaced by the default value.
Also, the rpc_server_listen() routine limits (according to its
max_calls_exec parameter) the amount of concurrent remote
procedure call execution. See the rpc_server_listen reference
page for more information.
if_handle
Specifies an interface specification containing the protocol
sequences and their corresponding endpoint information to use in
creating binding handles. Each created binding handle contains a
well-known (non-dynamic) endpoint contained in the interface
specification.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_calls_too_large_for_wk_ep
Maximum concurrent calls too large.
rpc_s_cant_bind_socket
Cannot bind to socket.
rpc_s_cant_create_socket
Cannot create socket.
rpc_s_cant_inq_socket
Cannot inquire endpoint from socket.
rpc_s_invalid_endpoint_format
Invalid interface handle.
rpc_s_max_descs_exceeded
Exceeded maximum number of network descriptors.
rpc_s_no_protseqs
No supported protocol sequences.
DESCRIPTION
The rpc_server_use_all_protseqs_if() routine registers all protocol
sequences and associated endpoint address information provided in the
IDL file with the RPC runtime. A server must register at least one
protocol sequence with the RPC runtime to receive remote procedure
call requests.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains
the well-known endpoint specified in the IDL file.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
If you want to register selected protocol sequences specified in the
IDL, your server uses rpc_server_use_protseq_if().
The explanation of rpc_server_use_all_protseqs() contains a list of
the routines a server typically calls after calling this routine.
(However, a server that uses only rpc_server_use_all_protseqs_if()
does not subsequently call rpc_ep_register() or
rpc_ep_register_no_replace().) For an explanation of how a server
can establish a client/server relationship without using the local
endpoint map or the name service database, see the information on
string bindings in the rpc_intro reference page.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_protseq
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
3.107 – rpc_server_use_protseq
NAME
rpc_server_use_protseq - Tells the RPC runtime to use the specified
protocol sequence for receiving remote
procedure calls
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_use_protseq( unsigned_char_t *protseq,
unsigned32 max_call_requests,
unsigned32 *status );
PARAMETERS
Input
protseq
Specifies a string identifier for the protocol sequence to
register with the RPC runtime. (For a list of string identifiers,
see the table of valid protocol sequences in the rpc_intro(3rpc)
reference page.)
max_call_requests
Specifies the maximum number of concurrent remote procedure call
requests that the server can accept.
The RPC runtime guarantees that the server can accept at least
this number of concurrent call requests. The actual number of
these requests can be greater than the value of max_call_requests
and can vary for each protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify the
default parameter value.
Note that in this version of DCE RPC, any number you specify is
replaced by the default value.
Also, rpc_server_listen() limits (according to its max_calls_exec
parameter) the amount of concurrent remote procedure call
execution. See the rpc_server_listen reference page for more
information.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_cant_create_socket
Cannot create socket.
rpc_s_invalid_rpc_protseq
Invalid protocol sequence.
rpc_s_max_descs_exceeded
Exceeded maximum number of network descriptors.
rpc_s_protseq_not_supported
Protocol sequence not supported on this host.
DESCRIPTION
The rpc_server_use_protseq() routine registers a single protocol
sequence with the RPC runtime. A server must register at least one
protocol sequence with the RPC runtime to receive remote procedure
call requests. A server can call this routine multiple times to
register additional protocol sequences.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains a
dynamic endpoint that the RPC runtime and operating system generated.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
A server calls rpc_server_use_all_protseqs() to register all protocol
sequences.
The explanation of the rpc_server_use_all_protseqs() routine contains
a list of the routines a server typically calls after calling this
routine. For an explanation of how a server can establish a
client/server relationship without using the local endpoint map or
the name service database, see the information on string bindings in
the rpc_intro reference page.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_network_is_protseq_valid
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq_ep
rpc_server_use_protseq_if
3.108 – rpc_server_use_protseq_ep
NAME
rpc_server_use_protseq_ep - Tells the RPC runtime to use the specified
protocol sequence combined with the
specified endpoint for receiving remote
procedure calls
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_use_protseq_ep( unsigned_char_t *protseq,
unsigned32 max_call_requests,
unsigned_char_t *endpoint,
unsigned32 *status );
PARAMETERS
Input
protseq
Specifies a string identifier for the protocol sequence to
register with the RPC runtime. (For a list of string
identifiers, see the table of valid protocol sequences in the
rpc_intro(3rpc) reference page.
max_call_requests
Specifies the maximum number of concurrent remote procedure call
requests that the server can accept.
The RPC runtime guarantees that the server can accept at least
this number of concurrent call requests. The actual number of
these requests can be greater than the value of max_call_requests
and can vary for each protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify the
default parameter value.
Note that in this version of DCE RPC, any number you specify is
replaced by the default value.
Also, rpc_server_listen() limits (according to its max_calls_exec
parameter) the amount of concurrent remote procedure call
execution. See the rpc_server_listen reference page for more
information.
endpoint
Specifies address information for an endpoint. This information
is used in creating a binding handle for the protocol sequence
specified in the protseq parameter.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_calls_too_large_for_wk_ep
Maximum concurrent calls too large.
rpc_s_cant_bind_socket
Cannot bind to socket.
rpc_s_cant_create_socket
Cannot create socket.
rpc_s_invalid_endpoint_format
Invalid endpoint format.
rpc_s_invalid_rpc_protseq
Invalid protocol sequence.
rpc_s_max_descs_exceeded
Exceeded maximum number of network descriptors.
rpc_s_protseq_not_supported
Protocol sequence not supported on this host.
DESCRIPTION
The rpc_server_use_protseq_ep() routine registers a protocol sequence
and its specified endpoint address information with the RPC runtime.
A server must register at least one protocol sequence with the RPC
runtime to receive remote procedure call requests. A server can call
this routine multiple times to register additional protocol sequences
and endpoints.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains
the well-known endpoint specified in the endpoint parameter.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
The explanation of rpc_server_use_all_protseqs() contains a list of
the routines a server typically calls after calling this routine.
For an explanation of how a server can establish a client/server
relationship without using the local endpoint map or the name service
database, see the information on string bindings in the rpc_intro
reference page.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
3.109 – rpc_server_use_protseq_if
NAME
rpc_server_use_protseq_if - Tells the RPC runtime to use the specified
protocol sequence combined with the
endpoints in the interface specification
for receiving remote procedure calls
Used by server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_server_use_protseq_if( unsigned_char_t *protseq,
unsigned32 max_call_requests,
rpc_if_handle_t if_handle,
unsigned32 *status );
PARAMETERS
Input
protseq
Specifies a string identifier for the protocol sequence to
register with the RPC runtime. For a list of string
identifiers, see the table of valid protocol sequences in the
rpc_intro(3rpc) reference page.
max_call_requests
Specifies the maximum number of concurrent remote procedure call
requests that the server can accept.
The RPC runtime guarantees that the server can accept at least
this number of concurrent call requests. The actual number of
these requests can be greater than the value of max_call_requests
and can vary for each protocol sequence.
Use the value rpc_c_protseq_max_reqs_default to specify the
default parameter value.
Note that in this version of DCE RPC, any number you specify is
replaced by the default value.
Also, the rpc_server_listen() routine limits (according to its
max_calls_exec parameter) the amount of concurrent remote
procedure call execution. See the rpc_server_listen reference
page for more information.
if_handle
Specifies an interface specification whose endpoint information
is used in creating a binding for the protocol sequence specified
in the protseq parameter. Each created binding handle contains a
well-known (nondynamic) endpoint contained in the interface
specification.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_calls_too_large_for_wk_ep
Maximum concurrent calls too large.
rpc_s_cant_bind_socket
Cannot bind to socket.
rpc_s_invalid_endpoint_format
Invalid endpoint format.
rpc_s_invalid_rpc_protseq
Invalid protocol sequence.
rpc_s_max_descs_exceeded
Exceeded maximum number of network descriptors.
rpc_s_protseq_not_supported
Protocol sequence not supported on this host.
DESCRIPTION
The rpc_server_use_protseq_if() routine registers one protocol
sequence with the RPC runtime, including its endpoint address
information as provided in the specified IDL file.
A server must register at least one protocol sequence with the RPC
runtime to receive remote procedure call requests. A server can call
this routine multiple times to register additional protocol sequences.
For each protocol sequence registered by a server, the RPC runtime
creates one or more binding handles. Each binding handle contains
the well-known endpoint specified in the IDL file.
The max_call_requests parameter allows you to specify the maximum
number of concurrent remote procedure call requests the server
handles.
To register all protocol sequences from the IDL, a server calls the
rpc_server_use_all_protseqs_if() routine.
The explanation of rpc_server_use_all_protseqs() contains a list of
the routines a server typically calls after calling this routine.
However, a server that uses only rpc_server_use_protseq_if() does not
subsequently call rpc_ep_register() or rpc_ep_register_no_replace().
For an explanation of how a server can establish a client/server
relationship without using the local endpoint map or the name service
database, see the information on string bindings in the rpc_intro
reference page.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_vector_free
rpc_ep_register
rpc_ep_register_no_replace
rpc_ns_binding_export
rpc_server_inq_bindings
rpc_server_listen
rpc_server_register_if
rpc_server_use_all_protseqs
rpc_server_use_all_protseqs_if
rpc_server_use_protseq
rpc_server_use_protseq_ep
3.110 – rpc_set_local_float_drep
Name:
rpc_set_local_float_drep - Sets the float type in the runtime to
the one with which the application is
being compiled
SYNOPSIS:
#include <dce/rpc.h>
void rpc_set_local_float_drep (unsigned8 float_drep,
unsigned32 *status);
PARAMETERS
Input
float_drep
The parameter should always be passed as using the
macro "RPC_APPLICATION_FLOAT_TYPE". This macro will
be define to 0 or 1 based on the compilation option
specified for the float type.
Output
status
The routine will always return "rpc_s_ok" status.
DESCRIPTION:
The routine rpc_set_local_float_drep allows the RPC application
to set the floating point type being used by the application
Only G_FLOAT and IEEE_FLOAT floating types are supported. This
routine if used,should be placed before any other API calls to
the RPC runtime. The first parameter float_drep should be passed
using the macro RPC_APPLICATION_FLOAT_TYPE that is defined in
IDLBASE.H header file. This macro will be set to appropriate value
based on the /FLOAT compilation option.
This routine can be used only on Alpha and I64 and will not be
supported on VAX.
RETURN TYPE:
No value is returned.
3.111 – rpc_sm_allocate
NAME
rpc_sm_allocate - Allocates memory within the RPC stub memory
management scheme
SYNOPSIS
#include <rpc.h>
idl_void_p_t rpc_sm_allocate ( unsigned long size,
unsigned32 *status );
PARAMETERS
Input
size Specifies, in bytes, the size of memory to be allocated.
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
Applications call rpc_sm_allocate to allocate memory within the RPC
stub memory management scheme. Before a call to this routine, the
stub memory management environment must have been established. For
manager code that is called from the stub, the stub itself normally
establishes the necessary environment. When rpc_sm_allocate is used
by code that is not called from the stub, the application must
establish the required memory management environment by calling
rpc_sm_enable_allocate.
When the stub establishes the memory management environment, the stub
itself frees any memory allocated by rpc_sm_allocate. The application
can free such memory before returning to the calling stub by calling
rpc_sm_free.
When the application establishes the memory management environment,
it must free any memory allocated, either by calling rpc_sm_free or
by calling rpc_sm_disable_allocate.
Multiple threads may call rpc_sm_allocate and rpc_sm_free to manage
the same memory within the stub memory management environment. To do
so, the threads must share the same stub memory management thread
handle. Applications pass thread handles from thread to thread by
calling rpc_sm_get_thread_handle and rpc_sm_set_thread_handle.
RETURN VALUES
A pointer to the allocated memory.
RELATED INFORMATION
Functions: rpc_sm_free
rpc_sm_enable_allocate
rpc_sm_disable_allocate
rpc_sm_get_thread_handle
rpc_sm_set_thread_handle
3.112 – rpc_sm_client_free
NAME
rpc_sm_client_free - Frees memory returned from a client stub
SYNOPSIS
#include <rpc.h>
void rpc_sm_client_free ( idl_void_p_t node_to_free,
unsigned32 *status );
PARAMETERS
Input
node_to_free
Specifies a pointer to memory returned from a client stub.
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
The rpc_sm_client_free routine releases memory allocated and returned
from a client stub. The thread calling rpc_sm_client_free must have
the same thread handle as the thread that made the RPC call.
Applications pass thread handles from thread to thread by calling
rpc_sm_get_thread_handle and rpc_sm_set_thread_handle.
This routine enables a routine to deallocate dynamically allocated
memory returned by an RPC call without knowledge of the memory
management environment from which it was called.
RETURN VALUES
None.
RELATED INFORMATION
Functions: rpc_sm_free
rpc_sm_get_thread_handle
rpc_sm_set_client_alloc_free
rpc_sm_set_thread_handle
rpc_sm_swap_client_alloc_free
3.113 – rpc_sm_destroy_client_context
NAME
rpc_sm_destroy_client_context - Reclaims the client memory resources
for a context handle, and sets the
context handle to null
SYNOPSIS
#include <rpc.h>
void rpc_sm_destroy_client_context(
idl_void_p_t p_unusable_context_handle,
unsigned32 *status );
PARAMETERS
Input
p_unusable_context_handle
Specifies the context handle that can no longer be accessed.
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
The rpc_sm_destroy_client_context routine is used by client
applications to reclaim the client resources used in maintaining
an active context handle. Applications call this routine after a
communications error makes the context handle unusable. When the
rpc_sm_destroy_client_context routine reclaims the memory resources,
it also sets the context handle to null.
RETURN VALUES
None.
3.114 – rpc_sm_disable_allocate
NAME
rpc_sm_disable_allocate - Releases resources and allocated memory
within the stub memory management scheme
SYNOPSIS
#include <rpc.h>
void rpc_sm_disable_allocate ( unsigned32 *status );
PARAMETERS
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
The rpc_sm_disable_allocate routine releases all resources acquired
by a call to rpc_sm_enable_allocate, and any memory allocated by calls
to rpc_sm_allocate after the call to rpc_sm_enable_allocate was made.
The rpc_sm_enable_allocate and rpc_sm_disable_allocate routines must
be used in matching pairs.
RELATED INFORMATION
Functions: rpc_sm_allocate
rpc_sm_enable_allocate
3.115 – rpc_sm_enable_allocate
NAME
rpc_sm_enable_allocate - Enables the stub memory managment environment
SYNOPSIS
#include <rpc.h>
void rpc_sm_enable_allocate( unsigned32 *status );
PARAMETERS
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
Applications can call rpc_sm_enable_allocate to establish a stub
memory management environment in cases where one is not established
by the stub itself. A stub memory management environment must be
established before any calls are made to rpc_sm_allocate. For server
manager code called from the stub, the stub memory management
environment is normally established by the stub itself. Code that is
called from other contexts needs to call rpc_sm_enable_allocate
before calling rpc_sm_allocate.
For a discussion of how spawned threads acquire a stub memory
management environment, see the rpc_sm_get_thread_handle and
rpc_sm_set_thread_handle reference pages.
RETURN VALUES
None
RELATED INFORMATION
Functions: rpc_sm_allocate
rpc_sm_disable_allocate
3.116 – rpc_sm_free
NAME
rpc_sm_free - Frees memory allocated by the rpc_sm_allocate routine
SYNOPSIS
#include <rpc.h>
void rpc_sm_free ( idl_void_p_t node_to_free,
unsigned32 *status );
PARAMETERS
Input
node_to_free
Specifies a pointer to memory allocated by rpc_sm_allocate.
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
Applications call rpc_sm_free to release memory allocated by
rpc_sm_allocate.
When the stub allocates memory within the stub memory management
environment, manager code called from the stub can also use
rpc_sm_free to release memory allocated by the stub.
The thread calling rpc_sm_free must have the same thread handle
as the thread that allocated the memory with rpc_sm_allocate.
Applications pass thread handles from thread to thread by calling
rpc_sm_get_thread_handle and rpc_sm_set_thread_handle.
RETURN VALUES
None.
RELATED INFORMATION
Functions: rpc_sm_allocate
rpc_sm_get_thread_handle
rpc_sm_set_thread_handle
3.117 – rpc_sm_get_thread_handle
NAME
rpc_sm_get_thread_handle - Gets a thread handle for the stub memory
management environment
SYNOPSIS
#include <rpc.h>
rpc_sm_thread_handle_t rpc_sm_get_thread_handle( unsigned32 *status );
PARAMETERS
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
Applications call rpc_sm_get_thread_handle to get a thread handle
for the current stub memory management environment. A thread that
is managing memory within the stub memory managment scheme calls
pc_sm_get_thread_handle to get a thread handle for its current stub
memory management environment. A thread that calls
rpc_sm_set_thread_handle with this handle, is able to use the same
memory management environment.
When multiple threads call rpc_sm_allocate and rpc_sm_free to manage
the same memory, they must share the same thread handle. The thread
that established the stub memory management environment calls
rpc_sm_get_thread_handle to get a thread handle before spawning new
threads that will manage the same memory. The spawned threads then
call rpc_sm_set_thread_handle with the handle provided by the parent
thread.
Typically, rpc_sm_get_thread_handle is called by a server manager
routine before it spawns additional threads. Normally the stub sets
up the memory management environment for the manager routine. The
manager calls rpc_sm_get_thread_handle to make this environment
available to the spawned threads.
A thread may also use rpc_sm_get_thread_handle and
rpc_sm_set_thread_handle to save and restore its memory
management environment.
RETURN VALUES
A thread handle.
RELATED INFORMATION
Functions: rpc_sm_allocate
rpc_sm_free
rpc_sm_set_thread_handle
3.118 – rpc_sm_set_client_alloc_free
NAME
rpc_sm_set_client_alloc_free - Sets the memory allocation and freeing
mechanisms used by the client stubs
SYNOPSIS
#include <rpc.h>
void rpc_sm_set_client_alloc_free (
idl_void_p_t (*p_allocate) (unsigned long size),
void (*p_free) (idl_void_p_t ptr),
unsigned32 *status );
PARAMETERS
Input
p_allocate
Specifies a memory allocator routine.
p_free Specifies a memory free routine. This routine is used to free
memory allocated with the routine specified by p_allocate.
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
The rpc_sm_set_client_alloc_free routine overrides the default
routines that the client stub uses to manage memory.
The default memory management routines are ISO malloc and ISO free
except when the remote call occurs within manager code in which case
the default memory management routines are rpc_sm_allocate and
rpc_sm_free.
RETURN VALUES
None.
RELATED INFORMATION
Functions: rpc_sm_allocate
rpc_sm_free
3.119 – rpc_sm_set_thread_handle
NAME
rpc_sm_set_thread_handle - Sets a thread handle for the stub memory
management environment
SYNOPSIS
#include <rpc.h>
void rpc_sm_set_thread_handle ( rpc_sm_thread_handle_t id,
unsigned32 *status );
PARAMETERS
Input
id Specifies a thread handle returned by a call to
rpc_sm_get_thread_handle.
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
An application thread calls rpc_sm_set_thread_handle to set a thread
handle for memory management within the stub memory management
environment. A thread that is managing memory within the stub memory
managment scheme calls rpc_sm_get_thread_handle to get a thread handle
for its current stub memory management environment. A thread that
calls rpc_sm_set_thread_handle with this handle is able to use the
same memory management environment.
When multiple threads call rpc_sm_allocate and rpc_sm_free to manage
the same memory, they must share the same thread handle. The thread
that established the stub memory management environment calls
rpc_sm_get_thread_handle to get a thread handle before spawning new
threads that will manage the same memory. The spawned threads then
call rpc_sm_set_thread_handle with the handle provided by the parent
thread.
Typically, rpc_sm_set_thread_handle is called by a thread spawned by
a server manager routine. Normally the stub sets up the memory
management environment for the manager routine and the manager calls
rpc_sm_get_thread_handle to get a thread handle. Each spawned thread
then calls rpc_sm_get_thread_handle to get access to the manager's
memory management environment.
A thread may also use rpc_sm_get_thread_handle and
rpc_sm_set_thread_handle to save and restore its memory
management environment.
RETURN VALUES
RELATED INFORMATION
Functions: rpc_sm_get_thread_handle
rpc_sm_allocate
rpc_sm_free
3.120 – rpc_sm_swap_client_alloc_free
NAME
rpc_sm_swap_client_alloc_free - Exchanges the current memory
allocation and freeing mechanism
used by the client stubs with one
supplied by the client
SYNOPSIS
#include <rpc.h>
void rpc_sm_swap_client_alloc_free (
idl_void_p_t (*p_allocate) (unsigned long size),
void (*p_free) (idl_void_p_t ptr),
idl_void_p_t (**p_p_old_allocate) (unsigned long size),
void (**p_p_old_free) (idl_void_p_t ptr),
unsigned32 *status );
PARAMETERS
Input
p_allocate
Specifies a new memory allocation routine.
p_free Specifies a new memory free routine.
Output
p_p_old_allocate
Returns the memory allocation routine in use before the
call to this routine.
p_p_old_free
Returns the memory free routine in use before the call to
this routine.
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
rpc_s_ok Success.
DESCRIPTION
The rpc_sm_swap_client_alloc_free routine exchanges the current
allocate and free mechanisms used by the client stubs for routines
supplied by the caller.
RETURN VALUES
None.
RELATED INFORMATION
Functions: rpc_sm_allocate
rpc_sm_free
rpc_sm_set_client_alloc_free
3.121 – rpc_ss_allocate
NAME
rpc_ss_allocate - Allocates memory within the RPC stub memory
management scheme
Used by server or possibly by client applications.
SYNOPSIS
#include <dce/rpc.h>
idl_void_p_t rpc_ss_allocate( idl_size_t size );
PARAMETERS
Input
size Specifies, in bytes, the size of memory to be allocated.
Note that in ANSI standard C environments, idl_void_p_t is defined as
void * and in other environments is defined as char *.
DESCRIPTION
Usually, the rpc_ss_allocate() routine is used in the manager code
that is called from a server stub. Memory allocated by
rpc_ss_allocate is released by the server stub after marshalling
any output parameters at the end of the remote call in which the
memory was allocated. If you want to release memory allocated by
rpc_ss_allocate() before returning from the manager code use
rpc_ss_free().
You can also use rpc_ss_free() in manager code to release memory
pointed to by a full pointer (ptr) in an input parameter.
When the server uses rpc_ss_allocate(), the server stub creates the
environment the routine needs. If the parameters of the operation
include any pointers other than those used for passing parameters by
reference, the environment is set up automatically.
If you need to use rpc_ss_allocate() in a manager code routine that
does not have a pointer in any of its parameters, use an ACF and apply
the enable_allocate attribute to the relevant operation. This causes
the generated server stub to set up the necessary environment.
Note that memory allocated by allocators other than rpc_ss_allocate()
is not released when the operation on the server side completes
execution.
If you want to use rpc_ss_allocate() outside the code called from a
server stub, you must first create an environment for it by calling
rpc_ss_enable_allocate().
See the OSF DCE Application Development Guide for more information.
RETURN VALUES
A pointer to the allocated memory.
An exception, rpc_x_no_memory, when no memory is available for
allocation.
RELATED INFORMATION
Functions: rpc_ss_free
rpc_ss_enable_allocate
rpc_ss_disable_allocate
rpc_ss_get_thread_handle
rpc_ss_set_thread_handle
3.122 – rpc_ss_bind_authn_client
NAME
rpc_ss_bind_authn_client - Authenticates a client's identity to a
server from a client stub
SYNOPSIS
#include <rpc.h>
void rpc_ss_bind_authn_client( rpc_binding_handle_t *binding,
if_handle_t if_handle,
error_status_t *status );
PARAMETERS
Input/Output
binding A pointer to the server binding handle for the remote
procedure call to which the routine will add
authentication and authorization context.
Input
if_handle
A stub-generated data structure that specifies the interface
of interest. The routine can use this parameter to resolve a
partial binding or to distinguish between interfaces.
Output
status Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not.
Possible status codes and their meanings include:
error_status_ok
Success.
rpc_s_no_more_bindings
Directs the client stub not to look for another
server binding.
DESCRIPTION
The rpc_ss_bind_authn_client() routine is a DCE-supplied binding
callout routine for use with the binding_callout ACF interface
attribute.
The binding_callout attribute enables applications to specify the
name of a routine that the client stub will call automatically to
modify a server binding handle with additional information before
it initiates a remote procedure call. This attribute is especially
useful for applications using the automatic binding method, where
it is the client stub that obtains the binding handle, rather than
the application code. The binding_callout attribute provides these
applications with a way to gain access to a server binding handle
from the client stub, since the handle is not accessible from the
application code.
Applications can specify rpc_ss_bind_authn_client() to the
binding_callout ACF interface attribute in order to authenticate
the client's identity to a server from the client stub before the
remote procedure call to the server is initiated. This routine
performs one-way authentication: the client does not care which
server principal receives the remote procedure call request, but
the server verifies that the client is who the client claims to be.
The routine sets the protection level used, the authentication
identity, and the authentication service used to their default
values; see the rpc_binding_set_auth_info reference pages for more
information on these default values. It sets the authorization
service to perform authorization based on the client's principal name.
Applications can also specify user-written binding callout routines
with the binding_callout attribute to modify server binding handles
from client stubs with other types of information. See the OSF DCE
Application Development Guide-Core Components for more information on
using the binding_callout ACF attribute.
RETURN VALUES
None.
RELATED INFORMATION
Functions: rpc_binding_set_auth_info
rpc_ep_resolve_binding
rpc_mgmt_inq_server_princ_name
Books: OSF DCE Application Development Guide-Introduction & Style
Guide
OSF DCE Application Development Guide-Core Components
3.123 – rpc_ss_client_free
NAME
rpc_ss_client_free - Frees memory returned from a client stub
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ss_client_free( idl_void_p_t node_to_free );
PARAMETERS
Input
node_to_free
Specifies a pointer to memory returned from a client stub.
DESCRIPTION
The rpc_ss_client_free() routine releases memory allocated and
returned from a client stub. The thread calling rpc_ss_client_free()
must have the same thread handle as the thread that made the RPC call.
This routine enables a routine to deallocate dynamically allocated
memory returned by an RPC call without knowledge of the memory
management environment from which it was called.
Note that while this routine is always called from client code, the
code can be executing as part of another server.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_ss_free
rpc_ss_get_thread_handle
rpc_ss_set_client_alloc_free
rpc_ss_set_thread_handle
rpc_ss_swap_client_alloc_free
3.124 – rpc_ss_destroy_client_context
NAME
rpc_ss_destroy_client_context - Reclaims the client memory resources
for the context handle, and sets the
context handle to NULL
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ss_destroy_client_context( void *p_unusable_context_handle );
PARAMETERS
Input
p_unusable_context_handle
Specifies the context handle that can no longer be
accessed.
DESCRIPTION
The rpc_ss_destroy_client_context() routine is used by the client
application to reclaim the client resources used in maintaining an
active context handle. Only call this after a communications error
makes the context handle unusable. When
rpc_ss_destroy_client_context() reclaims the memory resources, it
also sets the context handle to null.
RETURN VALUES
No value is returned.
The rpc_ss_destroy_client_context() routine raises no exceptions.
3.125 – rpc_ss_disable_allocate
NAME
rpc_ss_disable_allocate - Releases resources and allocated memory
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ss_disable_allocate( void );
DESCRIPTION
The rpc_ss_disable_allocate() routine releases (disables) all
resources acquired by a call to rpc_ss_enable_allocate(), and any
memory allocated by calls to rpc_ss_allocate() after the call to
rpc_ss_enable_allocate() was made.
The rpc_ss_enable_allocate() and rpc_ss_disable_allocate() routines
must be used in matching pairs.
For information about rules for using memory management routines, see
the OSF DCE Application Development Guide.
RELATED INFORMATION
Functions: rpc_ss_allocate
rpc_ss_enable_allocate
Books: OSF DCE Application Development Guide
3.126 – rpc_ss_enable_allocate
NAME
rpc_ss_enable_allocate - Enables the allocation of memory by the
rpc_ss_allocate() routine when not in
manager code
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ss_enable_allocate( void );
DESCRIPTION
In sophisticated servers, it may be necessary to call manager code
routines from different environments. This occurs, for example, when
the application is both a client and a server of the same interface.
Therefore, a manager code routine may need to be called both by the
application code and by the stub code. If code, other than manager
code, calls the rpc_ss_allocate() routine, it must first call
rpc_ss_enable_allocate() to initialize the memory management
environment that rpc_ss_allocate() uses.
For information about rules for using memory management routines, see
the OSF DCE Application Development Guide.
RETURN VALUES
An exception, rpc_x_no_memory, when there is insufficient memory
available to set up necessary data structures.
RELATED INFORMATION
Functions: rpc_ss_allocate
rpc_ss_disable_allocate
Books: OSF DCE Application Development Guide
3.127 – rpc_ss_free
NAME
rpc_ss_free - Frees memory allocated by the rpc_ss_allocate() routine
Used by server or possibly by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ss_free( idl_void_p_t node_to_free );
PARAMETERS
Input
node_to_free
Specifies a pointer to memory allocated by rpc_ss_allocate().
Note that in ANSI standard C environments, idl_void_p_t is defined
as void * and in other environments is defined as char *.
DESCRIPTION
The rpc_ss_free() routine releases memory allocated by
rpc_ss_allocate(). The thread calling rpc_ss_free() must have
the same thread handle as the thread that allocated the memory
with rpc_ss_allocate(). Use it only in an environment where
rpc_ss_allocate() is used.
If the manager code allocates memory with rpc_ss_allocate() and the
memory is not released by rpc_ss_free() during manager code execution,
then the server stub automatically releases the memory when the
manager code completes execution and returns control to the stub.
Manager code can also use rpc_ss_free() to release memory that is
pointed to by a full pointer in an input parameter.
For information about rules for using memory management routines,
see the OSF DCE Application Development Guide.
RELATED INFORMATION
Functions: rpc_ss_allocate
rpc_ss_get_thread_handle
rpc_ss_set_thread_handle
Books: OSF DCE Application Development Guide
3.128 – rpc_ss_get_thread_handle
NAME
rpc_ss_get_thread_handle - Gets a thread handle for the manager code
before it spawns additional threads, or
for the client code when it becomes a
server
Used by server or possibly by client applications.
SYNOPSIS
#include <dce/rpc.h>
rpc_ss_thread_handle_t rpc_ss_get_thread_handle( void );
DESCRIPTION
The rpc_ss_get_thread_handle() routine is used by a server manager
thread when it spawns additional threads. To spawn additional threads
that are able to perform memory management, the server manager code
calls rpc_ss_get_thread_handle() and passes the thread handle to each
spawned thread. Each spawned thread that uses rpc_ss_allocate() and
rpc_ss_free() for memory management must first call
rpc_ss_set_thread_handle(), using the handle obtained by the original
manager thread.
The rpc_ss_get_thread_handle() routine can also be used when a
program changes from being a client to being a server. The program
gets a handle on its environment as a client by calling
rpc_ss_get_thread_handle(). When the program reverts to being a
client it re-establishes the client environment by calling
rpc_ss_set_thread_handle(), supplying the previously obtained handle
as a parameter.
RETURN VALUES
A thread handle.
EXAMPLES
This function determines the thread handle, creates a thread, and
passes the thread handle to the thread so it can share the memory
management environment of the calling thread.
#include <pthread.h>
#include <idlbase.h>
pthread_t Launch_thread(
int (*routine_to_launch)(pthread_addr_t th)
)
{
rpc_ss_thread_handle_t th = rpc_ss_get_thread_handle();
pthread_t t;
/*
* Create the thread and pass to it the thread handle
* so it can use rpc_ss_set_thread_handle.
*/
pthread_create( &t,
pthread_attr_default,
(pthread_startroutine_t)routine_to_launch,
(pthread_addr_t)th );
return t;
}
RELATED INFORMATION
Functions: rpc_ss_allocate
rpc_ss_free
rpc_ss_set_thread_handle
3.129 – rpc_ss_set_client_alloc_free
NAME
rpc_ss_set_client_alloc_free - Sets 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
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ss_set_client_alloc_free(
idl_void_p_t (*p_allocate)(idl_size_t size),
void (*p_free)(idl_void_p_t *ptr) );
PARAMETERS
Input
p_allocate
Specifies a pointer to a routine that has the same procedure
declaration as the malloc() routine and that is used by the
client stub to allocate memory.
p_free
Specifies a pointer to a routine that has the same procedure
declaration as the free() routine and that is used to free
memory that was allocated using the routine pointed at by
p_allocate.
Note that in ANSI standard C environments, idl_void_p_t is defined
as void * and in other environments is defined as char *.
DESCRIPTION
The rpc_ss_set_client_alloc_free() routine overrides the default
routines that the client stub uses to manage memory for pointed-to
nodes. The default memory management routines are malloc() and
free(), except when the remote call occurs within manager code, in
which case the default memory management routines are
rpc_ss_allocate() and rpc_ss_free().
For information about rules for using memory management routines,
see the OSF DCE Application Development Guide.
RETURN VALUES
An exception, rpc_x_no_memory, when there is insufficient memory
available to set up necessary data structures.
RELATED INFORMATION
Functions: rpc_ss_allocate
rpc_ss_free
Books: OSF DCE Application Development Guide
3.130 – rpc_ss_set_thread_handle
NAME
rpc_ss_set_thread_handle - Sets 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
Used by server or possibly by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ss_set_thread_handle( rpc_ss_thread_handle_t id );
PARAMETERS
Input
id A thread handle returned by a call to rpc_ss_get_thread_handle().
DESCRIPTION
The rpc_ss_set_thread_handle() routine is used by a thread spawned
in the manager code to associate itself with the main RPC manager
thread. Each spawned thread that uses rpc_ss_allocate() and
rpc_ss_free() for memory management must call
rpc_ss_set_thread_handle(), using the handle that the main RPC
manager thread obtained through rpc_ss_get_thread_handle().
The rpc_ss_set_thread_handle() routine can also be used by a program
that originally was a client, then became a server, and is now
reverting to a client. The program must re-establish the client
environment by calling the rpc_ss_set_thread_handle() routine,
supplying the handle it received (through rpc_ss_get_thread_handle())
prior to becoming a server, as a parameter.
RETURN VALUES
An exception, rpc_x_no_memory, when there is insufficient memory
available to set up necessary data structures.
EXAMPLES
When this function is invoked within a spawned thread, its argument
is the thread handle of the calling thread. This example assumes the
data passed to the thread consists of only the middle thread.
#include <pthread.h>
#include <dce/idlbase.h>
int helper_thread (pthread_addr_t th)
{
/*
* Set the memory management environment to match
* the parent environment.
*/
rpc_ss_set_thread_handle(rpc_ss_thread_handle_t)th;
/*
* Real work of this thread follows here ...
*/
}
RELATED INFORMATION
Functions: rpc_ss_get_thread_handle
rpc_ss_allocate
rpc_ss_free
Books: OSF DCE Application Development Guide
3.131 – rpc_ss_swap_client_alloc_free
NAME
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
Used by client applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_ss_swap_client_alloc_free(
idl_void_p_t (*p_allocate)(idl_size_t size),
void (*p_free)(idl_void_p_t ptr),
idl_void_p_t (**p_p_old_allocate)(idl_size_t size),
void (**p_p_old_free)(idl_void_p_t ptr) );
PARAMETERS
Input
p_allocate
Specifies a pointer to a routine that has the same procedure
declaration as the malloc() routine and that is used for
allocating client stub memory.
p_free
Specifies a pointer to a routine that has the same procedure
declaration as the free() routine and that is used for freeing
client stub memory.
Output
p_p_old_allocate
Specifies a pointer to a pointer to a routine that has the same
procedure declaration as the malloc() routine. A pointer to the
routine that was previously used to allocate client stub memory
is returned in this parameter.
p_p_old_free
Specifies a pointer to a pointer to a routine that has the same
procedure declaration as the free() routine. A pointer to the
routine that was previously used to free client stub memory is
returned in this parameter.
Note that in ANSI standard C environments, idl_void_p_t is defined
as void * and in other environments is defined as char *.
DESCRIPTION
The rpc_ss_swap_client_alloc_free() routine exchanges the current
client allocate and free mechanism used by the client stubs for one
supplied by the caller. If it is appropriate for the client code
called by an application to use a certain memory allocation and
freeing mechanism, regardless of its caller's state, the client code
can swap its own mechanism into place on entry, replacing its
caller's mechanism. It can then swap the caller's mechanism back
into place prior to returning.
For information about rules for using memory management routines,
see the OSF DCE Application Development Guide.
RETURN VALUES
An exception, rpc_x_no_memory, is returned when there is insufficient
memory available to set up necessary data structures.
RELATED INFORMATION
Functions: rpc_ss_allocate
rpc_ss_free
rpc_ss_set_client_alloc_free
Books: OSF DCE Application Development Guide
3.132 – rpc_string_binding_compose
NAME
rpc_string_binding_compose - Combines the components of a string
binding into a string binding
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_string_binding_compose( unsigned_char_t *obj_uuid,
unsigned_char_t *protseq,
unsigned_char_t *network_addr,
unsigned_char_t *endpoint,
unsigned_char_t *options,
unsigned_char_t **string_binding,
unsigned32 *status );
PARAMETERS
Input
obj_uuid
Specifies a NULL-terminated string representation of an object
UUID.
protseq
Specifies a NULL-terminated string representation of a protocol
sequence.
network_addr
Specifies a NULL-terminated string representation of a network
address.
endpoint
Specifies a NULL-terminated string representation of an endpoint.
options
Specifies a NULL-terminated string representation of network
options.
Output
string_binding
Returns a pointer to a NULL-terminated string representation of
a binding handle.
Specify NULL to prevent the routine from returning this argument.
In this case the application does not call rpc_string_free().
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status code and its meaning is as follows:
rpc_s_ok Success.
DESCRIPTION
The rpc_string_binding_compose() routine combines string binding
handle components into a string binding handle.
The RPC runtime allocates memory for the string returned in the
string_binding parameter. The application calls rpc_string_free()
to deallocate that memory.
Specify NULL or provide a null string (\0) for each input string
that has no data.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_from_string_binding
rpc_binding_to_string_binding
rpc_string_binding_parse
rpc_string_free
uuid_to_string
3.133 – rpc_string_binding_parse
NAME
rpc_string_binding_parse - Returns, as separate strings, the
components of a string binding
Used by client or server applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_string_binding_parse( unsigned_char_t *string_binding,
unsigned_char_t **obj_uuid,
unsigned_char_t **protseq,
unsigned_char_t **network_addr,
unsigned_char_t **endpoint,
unsigned_char_t **network_options,
unsigned32 *status );
PARAMETERS
Input
string_binding
Specifies a NULL-terminated string representation of a binding.
Output
obj_uuid
Returns a pointer to a NULL-terminated string representation
of an object UUID. Specify NULL to prevent the routine from
returning this parameter. In this case the application does
not call rpc_string_free().
protseq
Returns a pointer to a NULL-terminated string representation
of a protocol sequence. Specify NULL to prevent the routine
from returning this parameter. In this case the application
does not call rpc_string_free().
network_addr
Returns a pointer to a NULL-terminated string representation
of a network address. Specify NULL to prevent the routine
from returning this parameter. In this case the application
does not call rpc_string_free().
endpoint
Returns a pointer to a NULL-terminated string representation of
an endpoint. Specify NULL to prevent the routine from returning
this parameter. In this case the application does not call
rpc_string_free().
network_options
Returns a pointer to a NULL-terminated string representation of
network options. Specify NULL to prevent the routine from
returning this parameter. In this case the application does
not call rpc_string_free().
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_invalid_string_binding Invalid string binding.
DESCRIPTION
The rpc_string_binding_parse() routine parses a string representation
of a binding handle into its component fields.
The RPC runtime allocates memory for each component string the
routine returns. The application calls rpc_string_free() once for
each returned string to deallocate the memory for that string.
If any field of the string_binding field is empty,
rpc_string_binding_parse() returns the empty string in the
corresponding output parameter.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_binding_from_string_binding
rpc_binding_to_string_binding
rpc_string_binding_compose
rpc_string_free
uuid_from_string
3.134 – rpc_string_free
NAME
rpc_string_free - Frees a character string allocated by the runtime
Used by client, server, or management applications.
SYNOPSIS
#include <dce/rpc.h>
void rpc_string_free( unsigned_char_t **string,
unsigned32 *status );
PARAMETERS
Input/Output
string
Specifies the address of the pointer to the character string to
free. The value NULL is returned.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status code and its meaning is as follows:
rpc_s_ok Success.
DESCRIPTION
The rpc_string_free() routine deallocates the memory occupied by a
character string returned by the RPC runtime.
An application must call this routine once for each character string
allocated and returned by calls to other RPC runtime routines. The
names of these routines appear at the end of this reference page.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: dce_error_inq_text
rpc_binding_inq_auth_client
rpc_binding_inq_auth_info
rpc_binding_to_string_binding
rpc_mgmt_ep_elt_inq_next
rpc_mgmt_inq_server_princ_name
rpc_ns_binding_inq_entry_name
rpc_ns_entry_expand_name
rpc_ns_group_mbr_inq_next
rpc_ns_profile_elt_inq_next
rpc_string_binding_compose
rpc_string_binding_parse
uuid_to_string
3.135 – uuid_compare
NAME
uuid_compare - Compares two UUIDs and determines their order
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
signed32 uuid_compare( uuid_t *uuid1,
uuid_t *uuid2,
unsigned32 *status );
PARAMETERS
Input
uuid1
Specifies a pointer to a UUID. This UUID is compared with the UUID
specified in uuid2. Use the value NULL to specify a nil UUID for
this parameter.
uuid2
Specifies a pointer to a UUID. This UUID is compared with the UUID
specified in uuid1. Use the value NULL to specify a nil UUID for
this parameter.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
uuid_s_ok Success.
uuid_s_bad_version Bad UUID version.
DESCRIPTION
The uuid_compare() routine compares two UUIDs and determines their
order. A nil UUID is considered the first element in order. The
order of UUIDs is defined by the RPC architecture and is not a
temporal (related to time) ordering. Comparing two specific UUIDs
always returns the same result regardless of the implementation or
system architecture.
You can use this routine to sort data with UUIDs as a key.
RETURN VALUES
Returns one of the following constants:
-1 The uuid1 parameter precedes the uuid2 parameter in order.
0 The uuid1 parameter is equal to the uuid2 parameter in order.
1 The uuid1 parameter follows the uuid2 parameter in order.
Note that a value of 0 (zero) has the same meaning as if
uuid_equal(&uuid1, &uuid2) returned a value of TRUE.
A nil UUID is the first UUID in order. This means the following:
+ If uuid1 is NULL and uuid2 is non-nil, the routine returns -1.
+ If uuid1 is NULL and uuid2 is NULL, the routine returns 0.
+ If uuid1 is non-nil and uuid2 is NULL, the routine returns 1.
RELATED INFORMATION
Functions: uuid_equal
uuid_is_nil
3.136 – uuid_create
NAME
uuid_create - Creates a new UUID
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
void uuid_create( uuid_t *uuid,
unsigned32 *status );
PARAMETERS
Input
None.
Output
uuid
Returns the new UUID.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
uuid_s_ok Success.
uuid_s_getconf_failure
Cannot get network interface device configuration.
uuid_s_no_address
Cannot get Ethernet hardware address.
uuid_s_socket_failure
Cannot create socket.
DESCRIPTION
The uuid_create() routine creates a new UUID.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: uuid_create_nil
uuid_from_string
uuid_to_string
3.137 – uuid_create_nil
NAME
uuid_create_nil - Creates a nil UUID
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
void uuid_create_nil( uuid_t *nil_uuid,
unsigned32 *status );
PARAMETERS
Input
None.
Output
nil_uuid
Returns a nil UUID.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status code and its meaning is as
follows:
uuid_s_ok Success.
DESCRIPTION
The uuid_create_nil() routine creates a nil UUID.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: uuid_create
3.138 – uuid_equal
NAME
uuid_equal - Determines if two UUIDs are equal
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
boolean32 uuid_equal( uuid_t *uuid1,
uuid_t *uuid2,
unsigned32 *status );
PARAMETERS
Input
uuid1
Specifies a pointer to a UUID. This UUID is compared with the
UUID specified in uuid2. Supply the value NULL to specify a nil
UUID for this parameter.
uuid2
Specifies a pointer to a UUID. This UUID is compared with the
UUID specified in uuid1. Supply the value NULL to specify a nil
UUID for this parameter.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
uuid_s_ok Success.
uuid_s_bad_version Bad UUID version.
DESCRIPTION
The uuid_equal() routine compares two UUIDs and determines if they
are equal.
RETURN VALUES
The possible return values and their meanings are as follows:
TRUE The uuid1 parameter is equal to the uuid2 parameter.
Parameter status contains the status code uuid_s_ok.
FALSE The uuid1 parameter is not equal to the uuid2 parameter.
RELATED INFORMATION
Functions: uuid_compare
3.139 – uuid_from_string
NAME
uuid_from_string - Converts a string UUID to its binary representation
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
void uuid_from_string( unsigned_char_t *string_uuid,
uuid_t *uuid,
unsigned32 *status );
PARAMETERS
Input
string_uuid
Specifies a string representation of a UUID. Supply the value
NULL or the null string (\0) to specify a nil UUID.
Output
uuid Returns the binary form of the UUID specified by the string_uuid
parameter into the address specified by this parameter.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
uuid_s_ok Success.
uuid_s_bad_version
Bad UUID version.
uuid_s_invalid_string_uuid
Invalid format for a string UUID.
DESCRIPTION
An application calls the uuid_from_string() routine to convert a
string UUID to its binary representation.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: uuid_to_string
3.140 – uuid_hash
NAME
uuid_hash - Creates a hash value for a UUID
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
unsigned16 uuid_hash( uuid_t *uuid,
unsigned32 *status );
PARAMETERS
Input
uuid
Specifies the UUID for which a hash value is created. Supply
NULL to specify a nil UUID for this parameter.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
uuid_s_ok Success.
uuid_s_bad_version Bad UUID version.
DESCRIPTION
The uuid_hash() routine generates a hash value for a specified UUID.
Note that the return value for a single uuid value may differ across
platforms.
RETURN VALUES
Returns a hash value for the specified UUID.
3.141 – uuid_is_nil
NAME
uuid_is_nil - Determines if a UUID is nil
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
boolean32 uuid_is_nil( uuid_t *uuid,
unsigned32 *status );
PARAMETERS
Input
uuid
Specifies a UUID to test as a nil UUID. Supply NULL to specify
a nil UUID for this parameter.
Output
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
uuid_s_ok Success.
uuid_s_bad_version Bad UUID version.
DESCRIPTION
The uuid_is_nil() routine determines whether the specified UUID is a
nil UUID. This routine yields the same result as if an application did
the following:
+ Called the uuid_create_nil() routine.
+ Called the uuid_equal() routine to compare the returned nil
UUID to the UUID specified in the uuid parameter.
RETURN VALUES
The possible return values and their meanings are as follows:
TRUE The uuid parameter is a nil UUID. Parameter status contains
the status code uuid_s_ok.
FALSE The uuid parameter is not a nil UUID.
RELATED INFORMATION
Functions: uuid_compare
uuid_create_nil
uuid_equal
3.142 – uuid_to_string
NAME
uuid_to_string - Converts a UUID from a binary representation to
a string representation
Used by client, server, or management applications.
SYNOPSIS
#include <dce/uuid.h>
void uuid_to_string( uuid_t *uuid,
unsigned_char_t **string_uuid,
unsigned32 *status );
PARAMETERS
Input
uuid Specifies a UUID in its binary format. Supply NULL to specify
a nil UUID for this parameter.
Output
string_uuid
Returns a pointer to the string representation of the UUID
specified in the uuid parameter. Specify NULL for this
parameter to prevent the routine from returning this
information.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if
not, why not. The possible status codes and their meanings
are as follows:
uuid_s_ok Success.
uuid_s_bad_version Bad UUID version.
DESCRIPTION
The uuid_to_string() routine converts a UUID from its binary
representation to its string representation.
The RPC runtime allocates memory for the string returned in the
string_uuid parameter. The application calls rpc_string_free() to
deallocate that memory. It is not necessary to call
rpc_string_free() when you supply NULL for the string_uuid
parameter.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: rpc_string_free
uuid_from_string
3.143 – wchar_t_from_netcs
NAME
wchar_t_from_netcs - Converts international character data from a
network code set to a local code set
Used by client and server applications.
SYNOPSIS
#include <dce/codesets_stub.h>
void wchar_t_from_netcs( rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
idl_byte *network_data,
unsigned32 network_data_length,
unsigned32 local_buffer_size,
wchar_t *local_data,
unsigned32 *local_data_length,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain code set
conversion information. When called from the client stub, this
value is the binding handle of a compatible server returned by the
rpc_ns_binding_import_next() or rpc_ns_binding_select() routine.
When called from the server stub, this value is a pointer to
binding information that the client stub passed in the RPC call.
network_code_set_value
The registered hexadecimal integer value that represents the code
set that was used to transmit character data over the network.
In general, the "network" code set is the code set that the
client application's code sets evaluation routine has determined
to be compatible for this client and server. When the caller is
the client stub, this value is the receiving tag. When the
caller is the server stub, this value is the sending tag.
network_data
A pointer to the international character data that has been
received, in the network code set encoding.
network_data_length
The number of byte data elements to be converted. This is the
size of the byte string that was sent through the network.
local_buffer_size
A pointer to the buffer size to be allocated to contain the
converted data, in units of wchar_t. The value specified in
this parameter is the local buffer size returned by the
wchar_t_local_size() routine.
Output
local_data
A pointer to the converted data, in wchar_t format.
local_data_length
The length of the converted data, in units of wchar_t. Specify
NULL if a fixed array is to be converted.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The specified code set does not match the code set
specified in the sending tag in the binding handle.
If this error occurs in the server stub, an
exception is raised to the client application.
When the routine is running the host converter routines, the following
errors can be returned:
rpc_s_ss_invalid_char_support
rpc_s_ss_short_conv_buffer
rpc_s_ss_iconv_error (HP-UX reference platform only)
rpc_s_ss_no_memory (HP-UX reference platform only)
When invoked from the server stub, this routine calls the
dce_cs_loc_to_rgy() routine and the host converter routines. If
one of these routines returns an error, an exception is raised to
the client application.
DESCRIPTION
The wchar_t_from_netcs() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and code
sets environment.
The wchar_t_from_netcs() routine is one of the DCE RPC stub code set
conversion routines that RPC stubs use before they marshall or
unmarshall data to convert international character data to and from
local and network code sets.
Client and server stubs call the wchar_t_*_netcs routines when the
wchar_t type has been specified as the local data type using the
cs_char attribute in the attribute configuration file for the
application.
Client and server stubs call the wchar_t_from_netcs() routine before
they unmarshall the international character data received from the
network. The routine takes a binding handle, a code set value that
identifies the code set used to transfer international character data
over the network, the address of the network data, in idl_byte format,
that may need to be converted, and the data length, in units of
idl_byte.
The routine compares the sending code set to the local code set
currently in use. If the routine finds that code set conversion is
necessary, (because the local code set differs from the code set
specified to be used on the network), it determines which host code
set converter to call to convert the data and then invokes that
converter.
The routine then returns the converted data, in wchar_t format. If
the data is a varying, conformant, or conformant varying array, the
routine also returns the length of the converted data, in units of
wchar_t.
Applications can specify local data types other than cs_byte and
wchar_t (the local data types for which DCE RPC supplies stub code
set conversion routines) with the cs_char ACF attribute. In this
case, the application must also supply local_type_to_netcs() and
local_type_from_netcs() stub conversion routines for this type.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: cs_byte_from_netcs
cs_byte_to_netcs
wchar_t_to_netcs
3.144 – wchar_t_local_size
NAME
wchar_t_local_size - Calculates the necessary buffer size for code
set conversion from a network code set to a
local code set
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>
void wchar_t_local_size( rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
unsigned32 network_buffer_size,
idl_cs_convert_t *conversion_type,
unsigned32 *local_buffer_size,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain buffer
size evaluation information. When called from the client stub,
this value is the binding handle of a compatible server returned
by the rpc_ns_binding_import_next() or rpc_ns_binding_select()
routine. When called from the server stub, this value is a
pointer to binding information that the client stub passed in
the RPC call.
network_code_set_value
The registered hexadecimal integer value that represents the code
set used to transmit character data over the network. In general,
the "network" code set is the code set that the client
application's code sets evaluation routine has determined to be
compatible for this client and server. When the caller is the
client stub, this value is the receiving tag. When the caller
is the server stub, this value is the sending tag.
network_buffer_size
The size, in units of idl_byte, of the buffer that is allocated
for the international character data, For a conformant or
conformant varying array, this value is the network value of the
size_is variable for the array; that is, the value is the size of
the unmarshalled string if no conversion is done.
Output
conversion_type
A pointer to the enumerated type defined in dce/idlbase.h that
indicates whether data conversion is necessary and whether or not
the existing buffer is sufficient for storing the results of the
conversion. Since idl_byte to wchar_t conversion always takes
place, and idl_byte and wchar_t require a different number of
bytes, the conversion type is always idl_cs_new_buffer_convert,
which means that the converted data must be written to a new
buffer.
local_buffer_size
A pointer to the buffer size that needs to be allocated to contain
the converted data, in units of wchar_t. This value is to be used
as the local value of the size_is variable for the array, and is
non-NULL only if a conformant or conformant varying array is to be
unmarshalled. A value of NULL in this parameter indicates that a
fixed or varying array is to be unmarshalled.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The specified code set does not match the code set
specified in the sending tag in the binding handle.
If this error occurs in the server stub, an exception
is raised to the client application.
When invoked from the server stub, this routine calls the routines
dce_cs_loc_to_rgy() and rpc_rgy_get_max_bytes(). If either of these
routines returns an error, the wchar_t_local_size() routine raises an
exception to the client application.
DESCRIPTION
The wchar_t_local_size() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The wchar_t_local_size() routine is one of the DCE RPC buffer sizing
routines that RPC stubs use before they marshall or unmarshall data
to determine whether or not the buffers allocated for code set
conversion need to be enlarged to hold the converted data. The buffer
sizing routines determine the type of conversion required and
calculate the size of the necessary buffer (if a conformant or
conformant varying array is to be marshalled). The RPC stub then
allocates a buffer of that size before it calls one of the code set
conversion routines.
Client and server stubs call the wchar_t_*_size routines when the
wchar_t type has been specified as the argument to the cs_char
attribute in the attribute configuration file for the application.
Applications do not call wchar_t_local_size() routine directly.
Client and server stubs call the routine before they unmarshall any
data. The stubs pass the routine a binding handle and a code set
value that identifies the code set that was used to transfer
international character data over the network. The stubs also
specify the network storage size of the data, in units of idl_byte.
When called from a client stub, the wchar_t_local_size() routine
determines the value of conversion_type from conversion method and
tag information set up in the binding handle by a code sets
evaluation routine or a tag-setting routine. Since idl_byte to
wchar_t require different numbers of bytes to encode one character
unit, the routine always sets the value to idl_cs_new_buffer_convert,
which means that the converted data must be written to a new buffer.
The routine sets the conversion_type parameter to this value and, if
a conformant or conformant varying array is to be unmarshalled,
calculates a new buffer size by dividing the value of
network_buffer_size by the number of bytes required to encode one
wchar_t unit. The routine returns the new buffer size in the
local_buffer_size parameter. The size is specified in units of
wchar_t, which is the local representation used for international
character data.
In cases where the binding handle does not contain the results of
character and code sets evaluation, or where it is being called from
the server stub, the wchar_t_local_size() routine determines the
value of conversion_type itself using the local code set value and
the code set value passed in the network_code_set_value parameter
and returns the appropriate conversion_type value. If a conformant
or conformant varying array is to be unmarshalled, the routine
calculates the size of this new buffer (by multiplying the value of
network_buffer_size by dividing the value of network_buffer_size by
the number of bytes required to encode one wchar_t unit, and returns
the results, in units of wchar_t, in local_buffer_size.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: byte_net_size
byte_local_size
wchar_t_net_size
3.145 – wchar_t_net_size
NAME
wchar_t_net_size - Calculates the necessary buffer size for code set
conversion from a local code set to a network code
set
Used by client and server applications.
SYNOPSIS
#include <dce/rpc.h>
void wchar_t_net_size( rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
unsigned32 local_buffer_size,
idl_cs_convert_t *conversion_type,
unsigned32 *network_buffer_size,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain buffer
size evaluation information. When called from the client stub,
this value is the binding handle of a compatible server returned
by the rpc_ns_binding_import_next() or rpc_ns_binding_select()
routine. When called from the server stub, this value is a
pointer to binding infor mation that the client stub passed in
the RPC call.
network_code_set_value
The registered hexadecimal integer value that represents the code
set to be used to transmit character data over the network. In
general, the "network" code set is the code set that the client
application's code sets evaluation routine has determined to be
compatible for this client and server. When the caller is the
client stub, this value is the sending tag. When the caller is
the server stub, this value is the receiving tag.
local_buffer_size
The size, in units of wchar_t, of the buffer that is allocated
for the international character data. This value is the local
value of the size_is variable for the array; that is, the value
is the size of the marshalled string if no conversion is done.
Output
conversion_type
A pointer to the enumerated type defined in dce/idlbase.h that
indicates whether data conversion is necessary and whether or
not the existing buffer is sufficient for storing the results of
the conversion. Because wchar_t to cs_byte conversion always
takes place, and because wchar_t and cs_byte are different units,
the conversion type returned is always idl_cs_new_buffer_convert,
which means that the converted data must be written to a new
buffer.
network_buffer_size
A pointer to the buffer size that needs to be allocated to contain
the converted data, in units of idl_byte. This value is to be used
as the network value of the size_is variable for the array, and is
non-NULL only if a conformant or conformant varying array is to be
marshalled. A value of NULL in this parameter indicates that a
fixed or varying array is to be marshalled.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not.
The possible status codes and their meanings are as follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The specified code set does not match the code set
specified in the sending tag in the binding handle.
If this error occurs in the server stub, an exception
is raised to the client application.
When invoked from the server stub, this routine calls the routines
dcs_cs_loc_to_rgy() and rpc_rgy_get_max_bytes(). If either of these
routines returns an error, the wchar_t_net_size() routine raises an
exception to the client application.
DESCRIPTION
The wchar_t_net_size() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The wchar_t_net_size() routine is one of the DCE RPC buffer sizing
routines that RPC stubs use before they marshall or unmarshall data
to determine whether or not the buffers allocated for code set
conversion need to be enlarged to hold the converted data. The
buffer sizing routines determine the type of conversion required
and calculate the size of the necessary buffer (if a conformant or
conformant varying array is to be marshalled). The RPC stub then
allocates a buffer of that size before it calls one of the code set
conversion routines.
Client and server stubs call the wchar_t_*_size routines when the
wchar_t type has been specified as the local data type with the
cs_char attribute in the attribute configuration file for the
application. Applications do not call the wchar_t_net_size() routine
directly. Client and server stubs call the routine before they
marshall any data. The stubs pass the routine a binding handle and a
code set value that identifies the code set to be used to transfer
international character data over the network. The stubs also specify
the local storage size of the data, in units of wchar_t.
When called from a client stub, the wchar_t_net_size routine
determines the value of conversion_type from conversion method and
tag information set up in the binding handle by a code sets
evaluation routine or a tag-setting routine. Since wchar_t and
idl_byte are completely different data types, the routine always
sets the value to idl_cs_new_buffer_convert. The routine sets the
conversion_type parameter to this value and, if a conformant or
conformant varying array is to be marshalled, calculates a new
buffer size by multiplying the value of local_buffer_size by the
byte size for wchar_t. The routine returns the new buffer size in
the network_buffer_size parameter. The size is specified in units
of idl_byte, which is the network representation used for
international character data.
In cases where the binding handle does not contain the results of
character and code sets evaluation, or where it is being called from
the server stub, the wchar_t_net_size routine determines the value of
conversion_type itself using the local code set value and the code set
value passed in the network_code_set_value parameter, and returns the
appropriate conversion_type value. If a conformant or conformant
varying array is to be marshalled, and the routine finds that a new
buffer is required to hold the converted data, the routine calculates
the size of this new buffer (by multiplying the value of
local_buffer_size by sizeof(wchar_t); that is, the number of bytes
required to encode one wchar_t data type, returns the results, in
units of idl_byte, in network_buffer_size.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: byte_local_size
byte_net_size
wchar_t_local_size
3.146 – wchar_t_to_netcs
NAME
wchar_t_to_netcs - Converts international character data from a local
code set to a network code set
Used by client and server applications.
SYNOPSIS
#include <dce/codesets_stub.h>
void wchar_t_to_netcs( rpc_binding_handle_t binding,
unsigned32 network_code_set_value,
wchar_t *local_data,
unsigned32 local_data_length,
idl_byte *network_data,
unsigned32 *network_data_length,
error_status_t *status );
PARAMETERS
Input
binding
Specifies the target binding handle from which to obtain code set
conversion information. When called from the client stub, this
value is the binding handle of a compatible server returned by the
rpc_ns_binding_import_next() or rpc_ns_binding_select() routine.
When called from the server stub, this value is a pointer to
binding information that the client stub passed in the RPC call.
network_code_set_value
The registered hexadecimal integer value that represents the code
set to be used to transmit character data over the network. In
general, the "network" code set is the code set that the client
application's code sets evaluation routine has determined to be
compatible for this client and server. When the caller is the
client stub, this value is the sending tag. When the caller is
the server stub, this value is the receiving tag.
local_data
A pointer to the international character data to be transmitted,
in the local code set encoding.
local_data_length
The number of wchar_t data elements to be converted. For a
varying array or a conformant varying array, this value is the
local value of the length_is variable. For a conformant array,
this value is the local value of the size_is variable. For a
fixed array, the value is the array size specified in the
interface definition.
Output
network_data
A pointer to the converted data, in idl_byte format.
network_data_length
A pointer to the length of the converted data, in units of
idl_byte. Specify NULL if a fixed or conformant array is to
be converted.
status
Returns the status code from this routine. This status code
indicates whether the routine completed successfully or, if not,
why not. The possible status codes and their meanings are as
follows:
rpc_s_ok Success.
rpc_s_ss_incompatible_codesets
The specified code set does not match the code set
specified in the sending tag in the binding handle.
If this error occurs in the server stub, an
exception is raised to the client application.
When this routine is running the host converter routines, the
following errors can be returned:
rpc_s_ss_invalid_char_input
rpc_s_ss_short_conv_buffer
rpc_s_ss_iconv_error (HP-UX reference platform only)
rpc_s_ss_no_memory (HP-UX reference platform only)
When invoked from the server stub, this routine calls the
dce_cs_loc_to_rgy() routine and host converter routines. If any of
these routines returns an error, an exception is raised to the
client application.
DESCRIPTION
The wchar_t_to_netcs() routine belongs to a set of DCE RPC routines
for use by client and server applications that are transferring
international character data in a heterogeneous character set and
code sets environment.
The wchar_t_to_netcs() routine is one of the DCE RPC stub code set
conversion routines that RPC stubs use before they marshall or
unmarshall data to convert international character data to and from
local and network code sets.
Client and server stubs call the wchar_t_*_netcs() routines when
the wchar_t type has been specified as the local data type with the
cs_char attribute in the attribute configuration file for the
application.
Client and server stubs call the wchar_t_to_netcs() routine before
they marshall any data. The routine takes a binding handle, a code
set value that identifies the code set to be used to transfer
international character data over the network, the address of the
data that may need to be converted, and the length of the data, in
units of wchar_t.
The routine first converts the character data from wchar_t values to
idl_byte values. The routine next compares the sending code set to
the local code set currently in use. If the routine finds that code
set conversion is necessary, (because the local code set differs from
the code set specified to be used on the network), it determines which
host code set converter to call to convert the data and then invokes
that converter.
The routine then returns the converted data, in units of idl_byte.
If the data is a varying, conformant, or conformant varying array,
the routine also returns the length of the converted data, in units
of idl_byte.
Applications can specify local data types other than cs_byte and
wchar_t (the local data types for which DCE RPC supplies stub support
routines for code set conversion) with the cs_char ACF attribute. In
this case, the application must also supply local_type_to_netcs() and
local_type_from_netcs() stub conversion routines for the application-
defined local type.
Permissions Required
No permissions are required.
RETURN VALUES
No value is returned.
RELATED INFORMATION
Functions: cs_byte_from_netcs
wchar_t_from_netcs
cs_byte_to_netcs
4 – Admin Intro
NAME
rpc_intro - Introduction to DCE RPC daemon and RPC control program
commands
DESCRIPTION
DCE RPC provides two administrative facilities, the RPC daemon and
the RPC control program. These facilities are superceded by the
DCE Host daemon (dced) and the DCE control program (dcecp) as of OSF
DCE version 1.1.
+ The RPC daemon is a process that provides the Endpoint Map
Service, which maintains the local endpoint map for local RPC
servers and looks up endpoints for RPC clients. An endpoint is
the address of a specific instance of a server executing in a
particular address space on a given system (a server instance).
Each endpoint can be used on a system by only one server at a
time.
An endpoint map is a database where servers register their
binding information, including endpoints, for each of their
RPC interfaces and the associated RPC objects. Each
combination of binding information, interface identifier, and
object UUID uses a distinct element in the local endoint map.
The RPC daemon is started via the DCE setup program
(@SYS$MANAGER:DCE$SETUP.COM).
+ The control program provides a set of commands for accessing the
operations of the RPC name service interface (NSI). For managing
endpoint maps, the control program supports showing endpoint map
elements and removing any set of map elements from the local
endpoint map or from any remote endpoint map.
The rpccp command starts the RPC control program (RPCCP).
EXIT VALUES
The RPC control program reports DCE error messages on the command line.
If the command executes successfully, the internal value returned is 1
(OpenVMS success); otherwise, the value is even (OpenVMS failure).
This is different from other DCE implementations, but allows the use of
standard OpenVMS mechanisms to determine success or failure upon return
from a DCE utility program.
RELATED INFORMATION
Commands: dced, dcecp, rpccp
Books: OSF DCE Administration Guide
OSF DCE Application Development Guide-Core Components
OSF DCE Application Development Reference
5 – idl
NAME
idl - Invokes the Interface Definition Language (IDL) compiler
SYNOPSIS
idl filename [argument] ...
DESCRIPTION
The idl command invokes the IDL compiler to convert an interface
definition, written in IDL, into output files. The output files
include a header file, server stub file, client stub file, and
auxiliary files. The compiler constructs the names of the output
files by keeping the basename of the interface definition source file
but replacing the filename extension with the new extension (or suffix
and extension) appropriate to the newly generated type of output file.
For example, math.idl could produce math_sstub.c or math_sstub.o for
the server stub.
The idl command accepts the following input:
+ An interface definition filename.
+ Arguments to indicate either special actions to be performed by
the compiler, or special properties of the input or output files.
The IDL compiler searches through directories for any related ACF.
For example, if you compile a file named source.idl, the compiler
automatically searches for a file named source.acf. The compiler
also searches for any imported IDL file (and its related ACF).
The compiler searches for these files using the following order:
1. The current working directory. The compiler always searches
this directory unless you specify the -no_def_idir and
-Idirectory arguments together.
2. Any imported directory. The compiler searches each directory you
are specifying in the -Idirectory argument.
3. The system IDL directory. The compiler automatically imports
nbase.idl, which resides in the system IDL directory. The
compiler always searches this directory unless you specify the
-no_def_idir argument.
4. The directory specified in the source filename. If you
explicitly specify a directory in the source IDL pathname,
then that directory is searched for the corresponding ACF.
For example,
$ idl /path/pathname/my_source.idl
causes the IDL compiler to look for /path/pathname/my_source.acf
if my_source.acf is not found in the directories in 1,2 and 3.
Note that this directory is not searched for any imported IDL file
or its corresponding ACF.
Restrictions
The following filenames are reserved by the IDL compiler. Naming an
IDL file with one of these names may result in unexpected behavior.
iovector.idl lbase.idl nbase.idl ncastat.idl
ndrold.idl rpc.idl rpcbase.idl rpcpvt.idl
rpcsts.idl rpctypes.idl twr.idl uuid.idl
CAUTIONS
The IDL compiler generates ANSI C code. It also supports C compilers
that are not fully ANSI compliant although a warning message may occur
during compilation of the stubs by the C compiler. A C compiler that
is not fully ANSI compliant may generate the following warning messages:
+ warning: & before array or function: ignored
+ warning: enumeration type clash, operator =
FILES
SYS$SYSTEM:DCE$IDL.EXE
Compiler
SYS$COMMON:[DCE$LIBRARY]
System IDL directory for imported files
SYS$COMMON:[DCE$LIBRARY]NBASE.IDL
Predefined IDL types
SYS$COMMON:[DCE$LIBRARY]<file.ext>
All .idl or .h files that are part of DCE RPC
RELATED INFORMATION
Books: OSF DCE Application Development Guide
5.1 – ARGUMENTS
5.1.1 – -client
-client file_type
Determines which client files to generate. If you do not specify
this argument, the compiler generates all client files. The file
types are as follows:
none Does not generate client files.
stub Generates only a client stub file.
aux Generates only a client auxiliary file. A client auxiliary
file is generated only if the interface contains any
out-of- line or self-pointing types.
all Generates client stub and client auxiliary files. This is
the default and is the same as not specifying the -client
argument.
5.1.2 – -server
-server file_type
Determines which server files to generate. If you do not specify
this argument, the compiler generates all server files. The file
types are as follows:
none Does not generate server files.
stub Generates only a server stub file.
aux Generates only a server auxiliary file. A server auxiliary
file is generated only if the interface contains any
out-of-line, self-pointing, or pipe types.
all Generates server stub and server auxiliary files. This is
the default and is the same as not specifying the -server
argument.
5.1.3 – -standard
-standard standard_type -
Allows you to specify portable or extended features of the OSF DCE.
This option is useful when you perform builds. The standard_type
argument specifies what IDL features to enable. If you do not
specify this argument, the compiler generates warning messages for
all features that are not available in the previous version of OSF
DCE.
You can specify one of the following values for the standard_type
argument:
portable
Allows only the language features available in OSF DCE
Version 1.0.2.
dce_v10
Synonymous with the portable argument.
dec_v10
Allows all language features supported by the standard
dce_v10 argument, plus a set of HP extensions to
its products based on OSF DCE Version 1.0.
extended
Allows all language features supported in the current
version of the compiler. This is the default.
dce_v11
Synonymous with the extended argument.
The following example command line compiles the IDL interface
test.idl and enables extended features of the OSF DCE:
% idl test.idl -standard extended
5.1.4 – -cstub
-cstub filename Specifies a pathname for the client stub file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -cstub argument, the idl compiler appends _cstub.c to the C source file and _cstub.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension.
5.1.5 – -sstub
-sstub filename Specifies a pathname for the server stub file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -sstub argument, the idl compiler appends _sstub.c to the C source file and _sstub.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension.
5.1.6 – -caux
-caux filename Specifies a pathname for the client auxiliary file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -caux argument, the idl compiler appends _caux.c to the C source file and _caux.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension.
5.1.7 – -saux
-saux filename Specifies a pathname for the server auxiliary file. When you give a filename, do not give a file extension; the idl compiler appends .c to the C source file and .o to the object file. If you do not use the -caux argument, the idl compiler appends _saux.c to the C source file and _saux.o to the object file. If the -lang cxx option is used, the source file will have the .cxx extension.
5.1.8 – -header
-header header_file Allows you to specify a name for the generated header file. By default the compiler takes the basename of the IDL file and appends the .h extension to it.
5.1.9 – -out
-out directory Places the output files in the directory you specify. By default the compiler places the output files in the current working directory.
5.1.10 – -Idirectory
-Idirectory Specifies a directory name that contains imported interface definition files. You can specify more than one directory by specifying additional -Idirectory arguments on the command line. The compiler searches the directories in the order you list them. If a file is present in more than one directory, the compiler takes the first occurrence of the file. The default behavior of the compiler is to first search the current directory, then all directories you specify, then the system IDL directory. The directory you specify is also passed to the C preprocessor and the C compiler.
5.1.11 – -no_def_idir
-no_def_idir Specifies that the compiler search only the current directory for imported files. When you use this with -Idirectory, the compiler searches only the directories you list, not the current directory, and not the system IDL directory.
5.1.12 – -no_mepv
-no_mepv Causes the compiler to not generate a manager entry point vector (EPV) in the server stub. Use this argument if the manager code and IDL file do not use the same operation names. If you specify this argument you must provide an EPV within the manager code that can be used when the interface is registered with the RPC server runtime. The name of the type that you construct an EPV with is if_name_vmajor-version_minor-version_epv_t where if_name is the interface name. It is not necessary to use this argument if the operation names in the manager code and IDL file are the same. In this case, the compiler generates a manager EPV in the server stub using the names of the operations in the IDL file. (For information on registering the server, see the intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.)
5.1.13 – -cepv
-cepv Generates local routines in the client stub file(<filename>_cstub.c) and defines a Client Entry Point Vector (CEPV) of the name if_name_vmajor-version_minor-version_c_epv where if_name is the interface name. The CEPV contains the addresses of the local routines. The client code must call the routines indirectly by using the addresses in the CEPV; otherwise, the stub routines in the client stub file must have the same names as the operations in the IDL file. (For information on registering the server, see the intro and rpc_server_register_if reference pages. See the OSF DCE Application Development Guide.)
5.1.14 – -cpp_cmd
-cpp_cmd 'c_preprocessor_command_line' Allows you to specify a C preprocessor other than the default. The compiler invokes the C preprocessor found in that command line. The output of the C preprocessor is an expanded version of the input file(s) containing replacement text for any preprocessor directives (for example, the #include preprocessor directive).
5.1.15 – -cpp_opt
-cpp_opt 'command_options' Specifies additional options to be passed to the C preprocessor. You can add options to the command line used to invoke the C preprocessor independent of the -cpp_cmd argument. The IDL compiler concatenates the -cpp_cmd, -cpp_opt, -D, -U, -I arguments and the source filename into a command used to invoke the C preprocessor. The compiler repeats this process for each Attribute Configuration File (ACF) and IDL file.
5.1.16 – -no_cpp
-no_cpp Does not invoke the C preprocessor. Note that the C preprocessor must be run on files that contain preprocessor directives (such as #include) in the interface definition.
5.1.17 – -cc_cmd
-cc_cmd 'command_line' Invokes the C compiler and compiler options you specify in the 'command_line' argument rather than the default C compiler and compiler options. When used with the -lang cxx option, the -cc_cmd option specifies the C++ compiler.
5.1.18 – -cc_opt
-cc_opt 'command_options' Specifies additional options to be passed to the C compiler. You can add options to the command line used to invoke the C compiler independent of the -cc_cmd argument. The IDL compiler concatenates the -cc_cmd, -cc_opt, -I arguments and the source filename into a command that invokes the C compiler. This procedure is done for each generated stub or auxiliary file. When used with the -lang cxx option, the -cc_opt option specifies the C++ compiler options.
5.1.19 – -Dname
-Dname[=definition] Defines a symbol name and an optional value to be passed to the C preprocessor. You can use this method of defining a symbol instead of using #define in the source code. You can use more than one -Dname argument on the command line. This argument has no effect if you use the -no_cpp argument.
5.1.20 – -Uname
-Uname Removes (undefines) any initial definition of a symbol name as defined by -Dname. You can use this method to remove a symbol name instead of using #undef in the source code. You can use more than one -Uname argument on the command line. This argument has no effect if you use the -no_cpp argument. If you define and undefine a name on the same command line, undefining takes precedence.
5.1.21 – -space_opt
-space_opt Generates code for the marshalling and unmarshalling of data that is optimized for space, rather than speed.
5.1.22 – -syntax_only
-syntax_only Checks only the syntax of the IDL file, but does not generate any output files.
5.1.23 – -keep
-keep file_types
Specifies which files to retain. To produce the object modules, the
IDL compiler first creates C source modules, then invokes the
target C compiler to produce object modules, and finally, deletes
the C source modules. If you do not use -keep, only the object
modules are saved.
The file types are as follows:
none Does not save the C source or the object modules. Does not
invoke the C compiler.
c_source
Saves only the C source modules. Does not invoke the C
compiler.
object Saves only the object modules.
all Saves both the C source and the object modules.
5.1.24 – -bug
-bug n, -no_bug n Retains (-bug) or does not retain (-no_bug) a specified bug from earlier IDL compiler versions. (This in an NCS compatibility argument and is not supported in OSF DCE Version 1.1).
5.1.25 – -stdin
-stdin
Takes the standard output of a previous utility as the input to the
idl command. For example:
$ pipe type my_filename.idl | idl -stdin
5.1.26 – -version
- version Displays the current version of the IDL compiler.
5.1.27 – -v
-v Prints informational messages (verbose mode) on the screen while the compiler is running.
5.1.28 – -no_warn
-no_warn Suppresses compiler warning messages.
5.1.29 – -confirm
-confirm Displays all the idl command arguments you chose, but does not compile the source IDL file. If you use this with the -v argument, informational messages about how the compiler behaves if you do not use -confirm are displayed but no corresponding actions are performed.
5.1.30 – -template_client
-template_client filename Requests that the IDL compiler generate a C source file containing a template implementation of each routine that must appear in the client application to use the specified IDL interface. If you do not specify an extension for filename, the compiler assigns the file extension .c.
5.1.31 – -template_manager
-template_manager filename Requests that the IDL compiler generate a C source file containing a template implementation of each routine and operation that must appear in the manager module of the server side of an application to use the specified IDL interface. If you do not specify an extension for filename, the compiler assigns the file extension .c.
5.1.32 – -trace
-trace value
Enables event logging.
You can specify one of the following values for the value argument:
all Log all events.
none Disable all previously specified trace options.
calls Log events relating to start and end of all RPC calls.
context
Log events relating to context handle creation, deletion,
and rundown.
errors
Log errors.
misc Log all miscellaneous events.
log_manager
Enable command interface support which allows
modification at runtime of event logging options.
5.1.33 – -lang
-lang {c, cxx, fortran}
Allows you to select a programming language.
If you are generating stubs and include files for application code
written in C++, you must specify cxx as the language of choice when
you compile the application's IDL file. When appropriate, you can
extend the class hierarchy and derive other classes from this one,
to implement some or all interface operations. The C++ compiler
gives a warning if any functions in the interface class have not
been implemented. Avoid overwriting the manager class header file
by using the -no_cxxmgr argument in conjunction with the -lang cxx
argument.
If you are generating stubs and include files for application code
written in FORTRAN, you must specify FORTRAN as the language of
choice when you compile the application's IDL file.
If you do not specify -lang fortran or -lang cxx, the default value
is the C programming language or -lang c.
5.1.34 – -no_cxxmgr
-no_cxxmgr Prevents the compiler from overwriting the manager class header file. Use this argument in conjunction with the -lang cxx argument if you implement application-specific C++ code in the manager class header file.
5.2 – EXAMPLES
1. Invoke the IDL compiler to compile the interface definition file
test.idl and keep the generated C source modules. Only server
files are generated. The server stub default filename is
overridden by creating a file named test_ss.c for the server
stub module.
$ idl test.idl -keep c_source -client none -sstub test_ss.c
2. Invoke the IDL compiler to compile the interface definition file
test.idl, but do not run the C preprocessor. The manager entry
point vector is not defined in the generated server stub module.
The IDL compiler searches the parent directory of the current
directory for any IDL files that test.idl could import. The
generated output files are located in the output subdirectory
under the current directory.
$ idl test.idl -no_cpp -no_mepv -I.. -out ./output
6 – rpclm
NAME
rpclm - Starts the command line interface to the RPC Event
Logger Log Manager
SYNOPSIS
rpclm "listening event string binding"
ARGUMENTS
inquire Inquire about the currently logged events and
determine the name of the active log file.
log Specify additional events to log: all,
none, calls, context, errors, or misc.
unlog Disable logging of the specified event types:
all, none, calls, context, errors, or misc.
file Change the output device or file to which events
are logged.
quit Terminate the rpclm session.
help Display a description of the rpclm command
interface commands.
6.1 – DESCRIPTION
The RPC Event Logger records information in an event log about
application execution. After enabling the Log Manager when you
compile the interface, you can use the Log Manager command line
options to modify event logging parameters at runtime.
Follow these steps to enable the RPC Log Manager:
1. Use the -trace log_manager option at IDL compilation time.
2. Create the RPC_LOG_FILE symbol and assign it to a file
name or to screen output.
3. Execute the client or server process, or both.
4. When the first call is made to an interface compiled
with the -trace option, a listening event will be
generated into the event log. Invoke the rpclm command
interface by specifying the string binding from the
listening event.
EXAMPLES
To enable the Log Manager, use the following syntax:
idl file-name.idl -trace log_manager
To invoke the rpclm command interface, specify the string binding
from a listening event, as in the following example:
rpclm ncacn_ip_tcp:16.31.48.144[3820]
The symbol rpclm is defined in the DCE$DEFINE_OPTIONAL_COMMANDS
command procedure. This command file can be found in
SYS$COMMON:[DCE$LIBRARY].
RELATED INFORMATION
"HP DCE for OpenVMS Alpha and OpenVMS I64 Product Guide"
7 – uuidgen
NAME
uuidgen - Generates a Universal Unique Identifier (UUID)
SYNOPSIS
uuidgen [argument] ...
Arguments
-c Allows you to supply an existing UUID that uuidgen then outputs
in the format you specify. This option is especially useful in
combination with the -s option for converting an existing UUID
into a C structure. You must specify the -c option at the end
of the uuidgen command line; all options that follow -c are
ignored.
-i Produces an Interface Definition Language (IDL) file template
and includes the generated UUID string in the template.
-o filename
Redirects the generated UUID string to the file you specify.
-s Generates a UUID string as an initialized C structure.
-v Displays the version number of the UUID generator, but does not
generate a UUID.
-h Displays information about the uuidgen command arguments. The
arguments -h and -? can be used interchangeably.
-? Displays information about the uuidgen command arguments. The
arguments -? and -h can be used interchangeably.
-n number_of_uuid_strings
Generates a specified number of UUID strings.
DESCRIPTION
The uuidgen command creates a UUID string that you assign to an object
to uniquely identify it. One such use is in the UUID interface attribute
of an IDL interface definition. The format for representing a UUID
string consists of eight hexadecimal digits followed by a dash,
followed by three groups of four hexadecimal digits separated by dashes,
followed by a dash and twelve hexadecimal digits:
01234567-89ab-cdef-0123-456789abcdef
The symbol uuidgen is defined in the DCE$DEFINE_OPTIONAL_COMMANDS
command procedure. This command file can be found in
SYS$COMMON:[DCE$LIBRARY].
FILES
The locations of files have the following pathnames:
SYS$SYSTEM:DCE$UUIDGEN.EXE
UUID Generator
EXAMPLES
1. Generate a UUID string:
$ uuidgen
23c67e00-71b6-11c9-9dfc-08002b0ecef1
2. Generate a partial template, containing a generated UUID string,
to be used to develop an interface definition:
$ uuidgen -i
[
uuid(828bf780-71b6-11c9-b5a8-08002b0ecef1),
version (1.0)
]
interface INTERFACENAME
{
}
3. Convert a UUID string from the old-style format to the new format:
$ uuidgen -t 34DC23469EAF.AB.A2.01.7C.5F.2C.ED.A3
34dc2346-9eaf-0000-aba2-017c5f2ceda3
4. Generate four UUID strings:
$ uuidgen -n 4
612c0b00-71b8-11c9-973a-08002b0ecef1
612c0b01-71b8-11c9-973a-08002b0ecef1
612c0b02-71b8-11c9-973a-08002b0ecef1
612c0b03-71b8-11c9-973a-08002b0ecef1
5. Convert a UUID into a C structure:
$ uuidgen -s -c 1251ace6-93al-11cd-95ad-0800097086e4
0x1251ace6,
0x93al,
0x11cd,
0x95,
0xad
{0x08, 0x00, 0x09, 0x70, 0x86, 0xe4}
};
RELATED_INFORMATION
Commands: uuidgen.
7.1 – UUIDGEN DCL Command Interface
This section provides DCL syntax for the UUID generation utility.
Except where noted, DCL commands are equivalent to the universal
command syntax documented in the uuidgen section of the OSF DCE
Application Development Reference. See the Reference documentation
for a complete description of the universal command syntax interface
to the UUID generation utility.
Users may choose to use either the universal interface to the
UUID generation utility or the DCL-style alternative.
NAME
IDENTIFIER/TRANSLATE - Translates a DCE RPC Version UUID to a
DCE RPC UUID.
SYNOPSIS
IDENTIFIER/TRANSLATE old-style-uuid [qualifier]...
QUALIFIERS
/OUTPUT=file
/OUTPUT=SYS$OUTPUT (default)
This qualifier, used with a file name, directs output to a
file. If you do not specify a file name, the converted UUID
goes to SYS$OUTPUT, generally your display terminal.
NAME
IDENTIFIER/GENERATE - Generates one or more DCE RPC
UUIDs.
SYNOPSIS
IDENTIFIER/GENERATE [qualifier]
QUALIFIERS
/FORMAT [=option]
Specify one or more of the following options.
STRING (default)
STRING Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
This is a raw UUID in its readable form.
IDL
IDL Format: [uuid(xxxxxxxx-xxxx-xxxx-xxxx- xxxxxxxxxxxx)]
This is a UUID as it appears syntactically in an RPC
interface definition.
STRUCT
STRUCT Format: This is an initialized C structure
declaration, which can be included in C code that is used
with DCE RPC.
/COUNT=n
This qualifier specifies the number of UUID strings to be
generated. If you do not specify a number for n, the number 1
is used by default.
/OUTPUT=file
/OUTPUT=SYS$OUTPUT (default)
This qualifier, used with a file name, directs output to a
file. If you do not specify a file name, the converted UUID
goes to SYS$OUTPUT, generally your display terminal.
8 – rpccp
NAME
rpccp - Starts the RPC control program
SYNOPSIS
rpccp [rpccp-command]
NOTES
This facility is superceded by the DCE control program (dcecp) for
OSF DCE version 1.1.
A server entry equates to an NSI binding attribute and, optionally,
an object attribute; a group equates to an NSI group attribute; and
a profile equates to an NSI profile attribute. Typically, each
server's entries, groups, and profiles reside in distinct name
service entries.
NOTES
With the exception of the rpccp_help subcommand, this command is
replaced at Revision 1.1 by the dcecp command. This command may be
fully replaced by the dcecp command in a future release of DCE, and
may no longer be supported at that time.
DESCRIPTION
The RPC control program (RPCCP) provides a set of commands for managing
name service use for RPC applications and for managing the endpoint map.
You can use control program commands from within the control program
or from the system prompt (represented here as a $).
To use the control program commands from inside the control program,
Start and enter the control program using the rpccp command alone,
without any argument. The control program then displays the control
program prompt (rpccp>), as follows:
$ rpccp
rpccp>
You can then enter any control program command, for example:
rpccp> show entry /.:/LandS/anthro/pr_server_node3
You leave the control program and return to the system prompt using
the exit or quit command.
If you enter invalid input, the control program displays the valid
commands.
To use the control program commands from the system prompt, enter the
rpccp command with an internal command of the control program as the
first argument. You can do this either interactively or in a command
procedure. For example, you can enter the show entry command as
follows:
$ rpccp show entry /.:/LandS/anthro/pr_server_node3
RELATED INFORMATION
Commands: dcecp
add element
add entry
add mapping
add member
export
import
remove element
remove entry
remove group
remove mapping
remove member
remove profile
show entry
show group
show mapping
show profile
show server
unexport
8.1 – ARGUMENTS
Arguments and Options
Except for the exit and quit commands, rpccp commands have one or more
options. Each option is identified by a - (dash) followed by a letter;
for example, -s. Some options require arguments.
Commands that access NSI operations also require the name of a name
service entry as an argument. The order of arguments and the
entry-name option is arbitrary; for example, the following placements
of arguments and options are equivalent:
rpccp> add element /.:/LandS/anthro/mis_node_2 \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.0
rpccp> add element -i ec1eeb60-5943-11c9-a309-08002b102989,1.0 \
> /.:/LandS/anthro/mis_node_2
rpccp-command
Specifies one of the following control program commands:
add element
Adds an element to a profile in a name service entry;
if the specified entry does not exist, creates the
entry.
add entry Adds an entry to the name service database.
add mapping
Adds or replaces server address information in the
local endpoint map.
add member
Adds a member to a group in a name service entry; if
the specified entry does not exist, creates the entry.
exit Leaves the RPC control program.
export Exports binding information for an interface identif-
ier, object UUIDs, or both to a server entry; if the
specified entry does not exist, creates the entry.
help Displays a list of commands or the possible options of
a specified command.
import Imports binding information and an object UUID from a
server entry.
quit Leaves the RPC control program.
remove element
Removes selected elements from a profile.
remove entry
Removes an entry from the name service database.
remove group
Removes all group members and the group from the
specified entry.
remove mapping
Removes specified elements from the local endpoint map
or from the endpoint map of a specified remote host.
remove member
Removes a selected member from a group.
remove profile
Removes all profile elements and the profile from the
specified entry.
show entry
Shows the NSI attributes of an entry.
show group
Shows the members of a group.
show mapping
Shows the elements of the local endpoint map.
show profile
Shows the elements of a profile.
show server
Shows the binding information, interface identifier,
and object UUIDs in a server entry.
unexport Removes binding information, interface identifiers,and
object UUIDs from a server entry.
8.1.1 – add_element
NAME
add element - Adds an element to a profile in a name service entry;
if the specified entry does not exist, creates the
entry.
SYNOPSIS
rpccp add element profile-entry-name -m member {-d | -i if-id
[-p priority]} [-a annotation] [-s syntax ]
OPTIONS
-m Defines a member name for the profile element to be added
(required).
-d Performs the add element operation on the default profile
element. With the -d option, the -i and -p options are
ignored.
-i Defines an interface identifier for the profile element to
be added. Only one interface can be added in a single
operation. An interface identifier is required, unless
the default profile element is being added. With the -d
option, the -i option is ignored. The value has the
following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are a decimal string, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,3.11
Leading zeros in version numbers are ignored.
-p Defines a search priority for the new profile element. The
priority value is in the range 0 to 7, with zero having
the highest priority. When a default element is added
(with the -d option), the -p option is ignored.By default,
a nondefault element is assigned a priority value of zero.
-a Defines an annotation string for the profile element.
Note that the shell supports quotation marks around the
annotation field of profile elements, which allows you to
include internal spaces in an annotation; the control
program does not. To specify or refer to annotations from
within the control program, limit each annotation to an
unbroken alphanumeric string; for example, CalendarGroup.
To refer to annotations from the system prompt, do not
incorporate quotation marks into any annotation.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
profile-entry-name
Specifies the entry name of the target profile. For an entry
in the local cell, you can omit the cell name and specify only
the cell-relative name.
DESCRIPTION
The add element command adds an element to a profile in a name
service entry. The name of the entry containing the profile and
the entry name of the profile member in the new element are
required. The entry of a profile may have been created previously
(by either the add entry or add element command). But, if the
specified entry does not exist, the add element command tries to
create the entry.
A profile element is a database record containing the following
fields:
Interface identifier
This is the primary search key. The interface identifier
consists of the interface UUID and the interface version
numbers.
Member name
The entry name of one of the following kinds of name service
entries:
+ A server entry for a server offering the requested RPC
interface and object
+ A group corresponding to the requested RPC interface
+ A profile
Priority value
The priority value (0 (zero) is the highest priority; 7 is the
lowest) is designated by the creator of a profile element to
help determine the order for using the element. NSI search
operations select among like priority elements at random. For
the rpccp add element command, the default is 0.
Annotation string
The annotation string enables you to identify the purpose of
the profile element. The annotation can be any textual
information, for example, an interface name associated with
the interface identifier or a description of a service or
resource associated with a group. The annotation string is
not a search key for the import or lookup operations.
Privilege Required
You need both read permission and write permission to the CDS object
entry (the target profile entry). If the entry does not exist, you
also need insert permission to the parent directory.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command adds an element to the cell profile,
/cell-profile, in the local cell:
$ rpccp
rpccp> add element \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -m /.:/Calendar_profile \
> -a RefersToCalendarGroups \
> /.:/cell-profile
The following control program commands start the control program,
set up a user profile associated with the cell profile as its
default element, and add a user-specific element for the Calendar
V1.1 interface, as follows:
$ rpccp
rpccp> add element /.:/LandS/anthro/molly_o_profile \
> -d -m /.:/cell-profile
rpccp>
rpccp> add element /.:/LandS/anthro/molly_o_profile \
> -m /.:/LandS/anthro/Calendar_group \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -a Calendar_Version 1.1_Interface
rpccp>
The added profile element contains the global name of the member
(specified using its cell-relative name,
/.:/LandS/anthro/Calendar_group) and the RPC interface identifier
for the Calendar Version 1.1 interface.
RELATED INFORMATION
Commands: remove element
remove profile
show profile
8.1.2 – add_entry
NAME
add entry - Adds a name service entry to the name service database
SYNOPSIS
rpccp add entry entry-name [-s syntax]
OPTIONS
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
entry-name
Specifies the name of the target name service entry. For
an entry in the local cell, you can omit the cell name and
specify only the cell-relative name.
DESCRIPTION
The add entry command adds an unspecialized entry to the name
service database. The name of the entry is required.
The new entry initially contains no NSI attributes. This command
creates a general name service entry for an application or user.
The application or user can later use the export, add element, and
add member commands to make the generic entry into a server entry,
a group, or a profile (or a combination), as follows:
+ For a server entry, specify the new entry as the target entry
for the rpccp export command.
+ For a group, specify the new entry as the target group for the
rpccp add member command.
+ For a profile, specify the new entry as the target profile for
the rpccp add element command.
The add entry command enables administrators to add entries for
users who lack the required permissions. If you have the
permissions required by the add entry command, you can also add an
entry using an export, add member, or add element command; if the
entry you specify does not exist, the command creates the entry.
Privilege Required
To add an entry, you need insert permission to the parent directory
and both read permission and write permission to the CDS object
entry (the target name service entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands start RPCCP and add an unspecialized entry to
the name service database:
$ rpccp
rpccp> add entry \
> /.:/LandS/anthro/Cal_host_2
The following command operates from the system prompt to add an
unspecialized entry to the name service database:
$ rpccp add entry \
> /.:/LandS/anthro/Cal_host_3
RELATED INFORMATION
Commands: remove entry
show entry
8.1.3 – add_mapping
NAME
add mapping - Adds or replaces server address information in the
local endpoint map
SYNOPSIS
rpccp add mapping -b string-binding -i interface-identifier
[-a annotation-string] [-o object-uuid] [-N]
OPTIONS
-b Specifies a string representation of a binding over which
the server can receive remote procedure calls. At least
one binding is required.
The value has the form of an RPC string binding, without
an object UUID, for example:
-b ncadg_ip_udp:63.0.2.17[5347]
Note that depending on your system, string binding
delimiters such as brackets ([ ]) may need to be preceded
by an escape symbol (\) or placed within quotation marks
(' ' or " "). Requirements vary from system to system,
and you must conform to the usage rules of a system.
-i Specifies an interface identifier to register with the
local endpoint map. An interface identifier is required.
Only one interface can be added (i.e., registered) in a
single operation. The interface identifier has the
following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-a Specifies a character string comment to be applied to each
cross product element that is added to the local endpoint
map. The string can be up to 64 characters long, including
the NULL terminating character.
The string is used by applications for informational
purposes only. The RPC runtime does not use this string
to determine which server instance a client communicates
with, or for enumerating endpoint map elements.
-o Defines an object UUID that further determines the
endpoint map elements that are removed (optional).
Each add mapping command accepts up to 32 -o options.
The UUID is a hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-N Specifies that existing elements in the local host's
endpoint map should not be replaced when the new
information is added.
DESCRIPTION
The add mapping command adds to, replaces, or adds server address
information to the local endpoint map.
Each element in the local endpoint map logically contains the
following:
+ Interface ID, consisting of an interface UUID and versions
(major and minor)
+ Binding information
+ Object UUID (optional)
+ Annotation (optional)
This command should be used without the -N option when only a single
instance of the server in question runs on the server's host. Do not
use the -N option if no more than one server instance on the host
ever offers the same interface UUID, object UUID, and protocol
sequence.
When local endpoint map elements are not replaced, obsolete elements
accumulate each time a server instance stops running without
explicitly unregistering its endpoint map information. Periodically,
the RPC Daemon (DCED) will identify these obsolete elements and
remove them. However, during the interval between these removals,
the presence of the obsolete elements increases the chance that
clients will receive endpoints to nonexistent servers. The clients
will then waste time trying to communicate with these servers before
giving up and obtaining another endpoint.
Allowing DCED to replace any existing local endpoint map elements
(by not specifying -N) reduces the chance of this happening.
For example, suppose an existing element in the local endpoint map
matches the interface UUID, binding information exclusive of the
endpoint, and object UUID of an element this routine provides. The
routine changes the endpoint map according to the elements'
interface major and minor version numbers.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command operates from the system prompt to add a map
element to the local endpoint map. The command adds the map element
that contains the specified interface identifier, server address
(specified as a string binding), and object UUIDs.
$ rpccp add mapping -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
-b ncadg_ip_udp:63.0.2.17[5347] \
-o 005077d8-8022-1acb-9375-10005a4f533a \
-o 001bc29a-8041-1acb-b377-10005a4f533a \
-a 'Calendar version 1.1'
$
The previous command adds the following elements:
interface ID
ec1eeb60-5943-1169-a309-08002b102989,1.1
string binding
ncadg_ip_udp:63.0.2.17[5347]
objects 005077d8-8022-1acb-9375-10005a4f533a
001bc29a-8041-1acb-b377-10005a4f533a
annotation
Calendar version 1.1
RELATED INFORMATION
Commands: export
remove mapping
show mapping
show server
Subroutines: rpc_ep_register
rpc_ep_register_no_replace
8.1.4 – add_member
NAME
add member - Adds a member to a group in a name service entry;
if the specified entry does not exist, creates the
entry
SYNOPSIS
rpccp add member group-entry-name -m member [-s syntax]
OPTIONS
-m Declares the name of a member to be added to the
specified group entry (required).
You can add only one member at a time.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
group-entry-name
Specifies the name of the target group. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The add member command adds a member to a group in a name service
entry. The name of the entry containing the group and the name of
the new group member are required. The entry of a group may have
been created previously (by either the add entry or add member
command). If the specified entry does not exist, the add member
command tries to create the entry.
Privilege Required
You need both read permission and write permission to the CDS object
entry (the target group entry). If the entry does not exist, you
also need insert permission to the parent directory.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and add the member
/.:/LandS/anthro/Cal_host_3 to the group
/.:/LandS/anthro/Calendar_group:
$ rpccp
rpccp> add member \
> -m /.:/LandS/anthro/Cal_host_3 \
> /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: remove group
remove member
show group
8.1.5 – export
NAME
export - Exports binding information for an interface identifier
or object UUIDs or both to a server entry; if the
specified entry does not exist, creates the entry
SYNOPSIS
rpccp export entry-name {-i if-id -b string-binding
[-b string-binding...] -o object-uuid
[-o object-uuid...] | -i if-id
-b string-binding [-b...] | -o object-uuid
[-o object-uuid...] } [-s syntax ]
OPTIONS
-i Declares the interface identifier of an RPC interface.
The export command operates on only one -i option; if you
enter more than one, the command ignores all but the last
interface identifier. If you specify an interface
identifier, you must specify at least one -b option. The
-i and -o options can occur together or separately, but
one of them is necessary. The interface identifier takes
the following form:
interface-uuid,major-version.minor-version
The version numbers are optional, but if you omit a
version number, the value defaults to 0. The UUID is
a hexadecimal string and the version numbers are decimal
strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,3.11
Leading zeros in version numbers are ignored.
-b Declares a string binding (optional). To use this option,
you must also specify an interface identifier (using the
-i option). Each command accepts up to 32 -b options.
The value has the form of an RPC string binding, without
an object UUID. The binding information contains an RPC
protocol sequence, a network address, and sometimes an
endpoint within brackets
(rpc-prot-seq:network-addr[endpoint]). For a well-known
endpoint, include the endpoint in the string binding, for
example:
-b ncadg_ip_udp:63.0.2.17[5347]
For a dynamic endpoint, omit the endpoint from the string
binding, for example:
-b ncacn_ip_tcp:16.20.15.25
Note that depending on your system, string binding
delimiters such as brackets ([ ]) may need to be preceded
by an escape symbol (\) or placed within quotation marks
(' ' or " "). Requirements vary from system to system,
and you must conform to the usage rules of a system.
-o Declares the UUID of an object. Each export command
accepts up to 32 -o options. The -i and -o options can
occur together or separately, but one of them is
necessary. The UUID is a hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
entry-name
Specifies the name of the target name service entry.
Usually, the target is a server entry. However, objects
also can be exported (without an interface identifier or
any binding information) to a group or a profile.
For an entry in the local cell, you can omit the cell
name and specify only the cell-relative name.
DESCRIPTION
The export command places binding information and an interface
identifier, object UUIDs, or both into a server entry, or the
command object UUIDs into a group's entry. The export command
searches the name service database for the entry with the specified
entry name. If the entry exists, the command uses it; otherwise,
the command tries to create a new name service entry using the
specified entry name.
Minimally, the command requires the name of the entry and either an
identifier and binding string or an object.
If the specified entry does not exist, the export command tries to
create the entry.
Privilege Required
You need both read permission and write permission to the CDS object
entry (the target name service entry). If the entry does not exist,
you also need insert permission to the parent directory.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
This example shows a control program export command that is stored
in a file for later execution from the system prompt. The command
exports two objects and an interface with two string bindings to the
server entry /.:/LandS/anthro/Cal_host_3 in the local cell:
# file to export Calendar 1.1 at installation time
rpccp export \
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
-b ncacn_ip_tcp:16.20.15.25 \
-b ncadg_ip_udp:63.0.2.17 \
-o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \
-o 16977538-e257-11c9-8dc0-08002b0f4528 \
/.:/LandS/anthro/Cal_host_3
The following example shows the use of a user-defined logical name
as an interface identifier, to facilitate entering an export command
interactively (in this case, from inside the control program). The
initial DCL command sets up a logical name Calendar_1_1, which
represents the interface identifier of an RPC interface. The rpccp
command then starts the control program, and the export command
exports the Calendar interface and two string bindings to the server
entry /.:/LandS/anthro/Cal_host_2 in the local cell, as follows:
$ define Calendar_1_1 ec1eeb60-5943-11c9-a309-08002b102989,1.1
$ rpccp
rpccp> export -i Calendar_1_1 \
> -b ncacn_ip_tcp:16.20.15.25 \
> -b ncadg_ip_udp:63.0.2.17 \
> /.:/LandS/anthro/Cal_host_2
The following example shows the use of user-defined logical names
for object UUIDs to facilitate entering an export command
interactively (in this case, from inside the control program).
The initial DCL commands set up the logical names LUKE_CAL and
JOSH_CAL, which represent personal calendars that are accessible
as objects to an RPC server. The rpccp command then starts the
control program, and the export command exports the two objects to
the server's entry /.:/LandS/anthro/Cal_host_2 in the local cell:
$ define LUKE_CAL 30dbeea0-fb6c-11c9-8eea-08002b0f4528
$ define JOSH_CAL 16977538-e257-11c9-8dc0-08002b0f4528
$ rpccp
rpccp> export -o LUKE_CAL -o JOSH_CAL \
> /.:/LandS/anthro/Cal_host_2
RELATED INFORMATION
Commands: import
show server
unexport
8.1.6 – help
NAME
help - Displays a list of commands or the options of a specified
command
SYNOPSIS
rpccp help [rpccp-command]
ARGUMENTS
rpccp-command
Specifies one of the following control commands:
add element
add entry
add member
exit
export
import
quit
remove element
remove entry
remove group
remove mapping
remove member
remove profile
show entry
show group
show mapping
show profile
show server
unexport
DESCRIPTION
The help command displays information about the RPCCP command set or
the options and argument associated with a specific command.
NOTE
This command may be replaced in future releases by the dcecp
command, and may no longer be supported at that time.
EXAMPLES
The following command operates from the system prompt to display the
internal commands of the control program:
$ rpccp help
The following commands start the control program and display the
syntax of the remove entry command:
$ rpccp
rpccp> help remove entry
RELATED INFORMATION
Commands: add element
add entry
add member
export
import
remove element
remove entry
remove group
remove mapping
remove member
remove
profile
rpccp
show entry
show group
show
mapping
show profile
show server
unexport
8.1.7 – import
NAME
import - Imports binding information and an object UUID from a
server entry
SYNOPSIS
rpccp import starting-entry-name -i if-id [-v versions] [-e]
[-n [integer]] [-o object-uuid] [-s syntax] [-u]
OPTIONS
-i Defines an interface identifier to be imported (required).
You can import only one interface at a time. The value has
the following form:
interface-uuid,major-version.minor-version The UUID is a
hexadecimal string and the version numbers are decimal
strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-v Indicates how a specified interface version is used
(optional). If it is used without the -i option, the
-v option is ignored. The possible combinations of
versions for the -v option and their actions are as
follows:
Versions Action
________________________________________________
all The interface version is ignored.
exact Both the major and minor versions
must match the specified versions.
compatible The major version must match the
specified version, and the minor
version must be greater than or
equal to the specified version.
major_only The major version must match the
specified version; the minor ver-
sion is ignored.
upto The major version must be less than
or equal to that specified. If the
major versions are equal, the minor
version must be less than or equal
to that specified.
________________________________________________
If the -v option is absent, the command shows compatible
version numbers.
-e Shows the name of the entry where the binding is found
(optional).
-n Declares that the import operation is to continue until no
more potential bindings are found (optional). Providing
a numeric value to this option restricts the number of
imported bindings. If you omit the number, only one
binding is imported. If repeated, this operation may
return the same binding. For example, -n imports all
available bindings, and -n 5 imports up to five bindings.
Note that the imported bindings are displayed as string
bindings.
-o Declares the UUID of an object to be imported (optional).
Only one UUID can occur in a single operation.
If an object is specified, the import operation limits its
search to server entries that contain both the specified
interface identifier and object UUID when searching for a
potential binding. Without the -o option, the import
operation ignores object UUIDs. The UUID is a hexadecimal
string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using the
-u option bypasses the local cache, allowing rpccp to go
directly to a CDS server for the inquiry. rpccp then
updates the local CDS cache.
ARGUMENTS
starting-entry-name
Indicates the name of the server entry where the import
operation starts. For an entry in the local cell, you
can omit the cell name and specify only the cell-relative
name.
DESCRIPTION
The import command imports binding information and an RPC object
UUID for a specific RPC interface from a server entry. The name
of the entry and the interface identifier are required. The entry
name can refer to a server entry, a group, or a profile.
Privilege Required
You need read permission to the specified CDS object entry (the
starting name service entry) and to any CDS object entry in the
resulting search path.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and import an interface and object:
$ rpccp
rpccp> import -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \
> /.:/LandS/anthro/Cal_host_3
RELATED INFORMATION
Commands: export
show server
unexport
8.1.8 – remove_element
NAME
remove element - Removes selected elements from a profile
SYNOPSIS
rpccp remove element profile-entry-name {-d | -i if-id -m member |
-a annotation} [-s syntax]
OPTIONS
-d Removes the default profile element. With the -d option,
the -a, -i, and -m options are ignored.
-i Defines an interface identifier for the profile element to
be removed for a member specified with the -m option. Only
one interface and member pair can be removed in a single
operation. If you supply multiple instances of the -i
option, the command uses the final instance.
The -i and -m options take precedence over the -a option.
However, if the default profile element is specified (by
the -d option), the -i and -m options are ignored.
The interface identifier value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-m Defines a member name for the profile element to be
removed. This option is required if the interface
identifier is specified. Only one interface and member
can be removed in a single operation. If you supply
multiple instances of the -m option, the command uses
the final instance.
-a Removes all elements whose annotation fields match the
specified annotation; in the presence of -d option or -i
and -m options, the -a option is ignored.
Note that the shell supports quotation marks around the
annotation field of profile elements, which allows you to
include internal spaces in an annotation; the control
program does not. To specify or refer to annotations from
within the control program, limit each annotation to an
unbroken alphanumeric string; for example, CalendarGroup.
To refer to annotations from the system prompt, do not
incorporate quotation marks into any annotation.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
profile-entry-name
Indicates the name of the target profile. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The remove element command removes an element from a profile in the
name service database. For a description of the fields in a profile
element, see add entry.
The remove element command requires the entry name of the profile.
The command also requires one of the following options:
-d The default profile option takes precedence over the other
two options.
-i interface-id -m member-name An interface and member pair
takes precedence over the -a option.
-a annotation-string
The annotation option takes effect only if neither the
-d or -i option is specified.
Privilege Required
You need read permission and write permission to the CDS object
entry (the target profile entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The initial DCL command sets up a logical name Calendar_1_1, which
represents the interface identifier of an RPC interface. The
control program commands set up a logical name for the interface
identifier of the Calendar Version 1.1 RPC interface, run RPCCP, and
remove an element from a profile, as follows:
$ define Calendar_1_1 ec1eeb60-5943-11c9-a309-08002b102989,1.1
$ rpccp
rpccp> remove element -i Calendar_1_1 \
> -m /.:/LandS/anthro/Calendar_group \
> /.:/LandS/anthro/molly_o_profile
RELATED INFORMATION
Commands: add element
remove profile
show profile
8.1.9 – remove_entry
NAME
remove entry - Removes a name service entry from the name service
database
SYNOPSIS
rpccp remove entry entry-name [-s syntax]
OPTIONS
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
entry-name
Indicates the name of the target name service entry. For
an entry in the local cell, you can omit the cell name and
specify only the cell-relative name.
DESCRIPTION
The remove entry command removes an entry from the name service
database. The name of the entry is required.
Privilege Required
You need read permission to the CDS object entry (the target name
service entry). You also need delete permission to the CDS object
entry or to the parent directory.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and remove the entry
/.:/LandS/anthro/Cal_host_2 from the local cell of the name service
database:
$ rpccp
rpccp> remove entry /.:/LandS/anthro/Cal_host_2
RELATED INFORMATION
Commands: add entry
show entry
8.1.10 – remove_group
NAME
remove group - Removes all group members and the group from the
specified name service entry
SYNOPSIS
rpccp remove group group-entry-name [-s syntax]
OPTIONS
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
group-entry-name
Indicates the name of the target group. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The remove group command removes a group from the name service
database. The group need not be empty. The entry name of the group
is required.
Privilege Required
You need write permission to the CDS object entry (the target group
entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and remove the group from the name
service entry /.:/LandS/anthro/Calendar_group:
$ rpccp
rpccp> remove group /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: add member
remove member
show group
8.1.11 – remove_mapping
NAME
remove mapping - Removes specified elements from the local endpoint
map
SYNOPSIS
rpccp remove mapping -b string-binding -i interface-identifier
[-o object-uuid]
OPTIONS
-b Specifies a string representation of a binding over which
the server can receive remote procedure calls. At least
one binding is required. The value has the form of an RPC
string binding, without an object UUID, for example:
-b ncadg_ip_udp:63.0.2.17[5347]
Note that depending on your system, string binding
delimiters such as brackets ([ ]) may need to be preceded
by an escape symbol (\) or placed within quotation marks
(' ' or " "). Requirements vary from system to system,
and you must conform to the usage rules of a system.
-i Specifies an interface identifier to remove from the local
endpoint map. An interface identifier is required. Only
one interface can be removed in a single operation. The
interface identifier has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-o Defines an object UUID that further determines the
endpoint map elements that are removed (optional).
Each remove mapping command accepts up to 32 -o options.
The UUID is a hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
DESCRIPTION
The remove mapping command removes server address information from
the local endpoint map. Each element in the local endpoint map
logically contains the following:
+ Interface ID, consisting of an interface UUID and versions
(major and minor)
+ Binding information
+ Object UUID (optional)
+ Annotation (optional)
This command requires one interface identifier (the -i option); at
least one string binding (the -b option); and optionally, one or
more object UUIDs (the -o option). Each instance of the command
accepts from 1 to 32 -b options and from 0 to 32 -o options. The
options work together to delimit the elements to be removed from the
target endpoint map. The command removes any map element that
contains the specified interface identifier, a specified string
binding, and a specified object UUID (if any).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command operates from the system prompt to remove a
map element from the local endpoint map. The command removes only
the map element that contains the specified interface identifier,
server address (specified as a string binding), and object UUID.
$ rpccp remove mapping \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -b ncadg_ip_udp:16.20.16.64[3424] \
> -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528
$
RELATED INFORMATION
Commands: add mapping
show mapping
show server
8.1.12 – remove_member
NAME
remove member - Removes a specified member from a group
SYNOPSIS
rpccp remove member group-entry-name -m member [-s syntax]
OPTIONS
-m Declares the entry name of the group member to be removed
(required).
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
group-entry-name
Indicates the name of the target group. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The remove member command removes a specified member from
a specified group.
Privilege Required
You need read permission and write permission to the CDS object
entry (the target group entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and remove the member
/.:/LandS/anthro/Cal_host_2 from the group
/.:/LandS/dept/Calendar_group:
$ rpccp
rpccp> remove member \
> -m /.:/LandS/anthro/Cal_host_2 \
> /.:/LandS/anthro/Calendar_group
The following command removes the member /.:/LandS/anthro/Cal_host_3
from the group /.:/LandS/anthro/Calendar_group:
$ rpccp remove member \
> -m /.:/LandS/anthro/Cal_host_3 \
> /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: add member
remove group
show group
8.1.13 – remove_profile
NAME
remove profile - Removes all profile elements and the profile
from the specified name service entry
SYNOPSIS
rpccp remove profile profile-entry-name [-s syntax]
OPTIONS
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
profile-entry-name
Indicates the name of the target profile. For an entry
in the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The remove profile command removes a profile (and all of its
elements) from the name service database. The entry name of the
profile is required.
Privilege Required
You need write permission to the CDS object entry (the target
profile entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands run RPCCP and remove the profile named
/.:/LandS/anthro/molly_o_profile:
$ rpccp
rpccp> remove profile /.:/LandS/anthro/molly_o_profile
RELATED INFORMATION
Commands: add element
remove element
show profile
8.1.14 – show_entry
NAME
show entry - Shows the NSI attributes of a name service entry
SYNOPSIS
rpccp show entry entry-name [-i if-id] [-s syntax] [-u]
OPTIONS
-i Selects a specified interface identifier (optional).
Only elements containing that identifier are shown.
The interface identifier value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using the
-u option bypasses the local cache, allowing rpccp to go
directly to a CDS server for the inquiry. rpccp then
updates the local CDS cache.
ARGUMENTS
entry-name
Indicates the name of the target name service entry.
For an entry in the local cell, you can omit the cell
name and specify only the cell-relative name.
DESCRIPTION
The show entry command shows the NSI attributes of a name service
entry. The name of the entry is required.
Note that this operation shows all of the compatible bindings for a
given interface.
The show entry command shows the same list of string bindings as the
import operation returns for the specified entry. This list includes
all string bindings that refer to a major version that matches the
specified version and a minor version that is equal to or greater
than the specified version. The list may include string bindings
exported for other versions of the interface that are upwardly
compatible, rather than for this particular version of the
interface.
Privilege Required
You need read permission to the CDS object entry (the target name
service entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command operates from the system prompt to show the
name service entry /.:/LandS/anthro/calendar_mgr_node_3.
$ rpccp show entry /.:/LandS/anthro/Cal_host_3
The following commands run the control program and show the name
service entry /.:/LandS/anthro/Calendar_group:
$ rpccp
rpccp> show entry \
> /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: add entry
remove entry
8.1.15 – show_group
NAME
show group - Shows the members of a group
SYNOPSIS
rpccp show group group-entry-name [-m member] [-r [integer]]
[-s syntax] [-u]
OPTIONS
-m Declares the name of a single group member.
-r Indicates that the show group operation recurses. If
any members of a group are also groups, their entries are
shown. By default, the -r option causes the show group
operation to recurse until all nested groups are expanded;
for example, -r shows the members of the specified group
and all nested groups. You can limit recursion to one or
more levels by specifying a decimal integer as part of the
-r option. For example, -r 1 shows the members of the
specified group and, for members that are groups, the
command also shows their members; then recursion stops.
Without the -r option, only the members of the specified
group are shown.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using the
-u option bypasses the local cache, allowing rpccp to go
directly to a CDS server for the inquiry. rpccp then
updates the local CDS cache.
ARGUMENTS
group-entry-name
Indicates the name of the target group. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The show group command shows the members of a group in the name
service database. The entry name of the group is required. Unless
it is limited to a specific member (by the -m option), the show
group command shows all members. The command shows only the members
in the specified group; the -r option enables you to show members of
nested groups.
Privilege Required
You need read permission to the CDS object entry (the target group
entry). If you use the -r option, you also need read permission
to any nested groups.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following example shows all the members of the group
/.:/LandS/anthro/Calendar_group, in the order in which they were
added to the group:
$ rpccp
rpccp> show group /.:/LandS/anthro/Calendar_group
The following command operates from the system prompt to show a
specific member of the group /.:/LandS/dept/Calendar_group:
$ rpccp show group \
> -m /.:/LandS/anthro/Cal_host_2 \
> /.:/LandS/anthro/Calendar_group
RELATED INFORMATION
Commands: add member
remove group
remove member
8.1.16 – show_mapping
NAME
show mapping - Shows the elements of the either the local or a
remote endpoint map
SYNOPSIS
rpccp show mapping [host-address] [-i if-id [-v versions]]
[-o object-uuid [ -o object-uuid...]]
OPTIONS
-i Defines an interface identifier to be shown (optional).
Only one interface can be shown in a single operation.
If specified, only elements containing this interface
identifier are shown. The -i option can be qualified by
the -v option. The value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-v Indicates how a specified interface version is used
(optional). If it is used without the -i option, the
-v option is ignored. The possible combinations of
versions for the -v option and their actions are
described in the following table.
________________________________________________
Versions Action
________________________________________________
all The interface version is ignored.
exact Both the major and minor versions
must match the specified versions.
compatible The major version must match the
specified version, and the minor
version must be greater than or
equal to the specified version.
major_only The major version must match the
specified version; the minor ver-
sion is ignored.
upto The major version must be less than
or equal to that specified. If the
major versions are equal, the minor
version must be less than or equal
to that specified.
________________________________________________
If the -v option is absent, the command shows compatible
version numbers.
-o Defines an object to be shown (optional). Each show
mapping command accepts up to 32 -o options. The UUID
is a hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
ARGUMENTS
host-address
The host-address argument is a string binding that
indicates where to find the target endpoint map. When
accessing the local endpoint map, you can specify which
protocol sequence to use (optional); for example,
ncadg_ip_udp:
When accessing a remote endpoint map, you must specify
both a protocol sequence and a network address for the
remote system (required); for example,
ncadg_ip_udp:16.20.16.44
An endpoint is unnecessary in local or remote host
addresses, and the remove mapping command ignores any
endpoint specified as part of a host address.
DESCRIPTION
The show mapping command shows elements of an endpoint map.
Each element corresponds to an object UUID, interface identifier,
annotation, and binding information. The binding information
contains an RPC protocol sequence, a network address, and an
endpoint within square brackets
(rpc- protseq:network-addr[endpoint]).
The endpoint map can be either the local endpoint map or the
endpoint map of a specified remote host. If entered without
a remote host address, the command accesses the local endpoint
map. For the local endpoint map, a show mapping command without
any options displays all the map elements. For a remote endpoint
map, map elements are accessible only for protocol sequences that
are supported on both your system and the remote system.
The options list a selected subset of map elements. The - i option
selects a specific interface, and the -v option qualifies the -i
option. The -o object selects a specific object. You can use from
0 to 32 -o options per command. The options work together to
specify the subset of elements for the target protocol sequence(s).
NOTES
Note that to ensure that you can remotely display all map elements
from every remote endpoint map, run the RPC control program on a
system that supports all of the protocol sequences available in
your network environment.
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands start the control program and show the map
elements in the local endpoint map that contain the specified
interface identifier:
$ rpccp
rpccp> show mapping -i ec1eeb60-5943-11c9-a309-08002b102989,1.1
The following rpccp show mapping command operates from the system
prompt. The command accesses the endpoint map of the remote host
specified by the host address (ncadg_ip_udp:16.20.16.44) and
displays the one map element that contains both the specified
interface identifier and the specified object UUID:
$ rpccp show mapping \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1 \
> -o 30dbeea0-fb6c-11c9-8eea-08002b0f4528 \
> ncadg_ip_udp:16.20.16.44
RELATED INFORMATION
Commands: remove mapping
show server
8.1.17 – show_profile
NAME
show profile - Shows the elements of a profile
SYNOPSIS
rpccp show profile profile-entry-name {-d | -a annotation |
-i if-id [-v versions] -m member}
[-r [integer]] [-s syntax] [-u]
OPTIONS
-d Selects the default profile element. With the -d option,
the -a, -i, and -m options are ignored.
Note that the -a option works with the -d option, but do
not use them together.
-a Declares a single annotation field (optional). The -a
option selects only elements containing the specified
annotation. The option is case sensitive.
The -a option works alone or in combination with the -i
or -m options or both; only elements containing all the
specified values are displayed.
Note that the shell supports quotation marks around the
annotation field of profile elements, allowing you to
include internal spaces in an annotation; the control
program does not. To specify or refer to annotations
from within the control program, limit each annotation
to an unbroken alphanumeric string; for example,
CalendarGroup. To refer to annotations from the system
prompt, do not incorporate quotation marks into any
annotation.
-i Selects a specified interface identifier (optional).
Only elements containing that interface identifier are
shown. The interface identifier value has the following
form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
The -i option works alone or in combination with the -a
or -m options or both; only elements containing all the
specified values are displayed. When the -d option is
specified, the -i option is ignored.
-m Declares a single member name (optional). Only elements
containing that member name are shown.
The -m option works alone or in combination with the -a
or -i options or both; only elements containing all the
specified values are displayed. When the -d option is
specified, the -m option is ignored.
-r Indicates that the show profile operation recurses. If
the member of any element of a profile is also a profile,
its elements are shown. By default, the -r option causes
the show profile operation to recurse until all nested
profiles are expanded; for example, -r shows the elements
of the specified profile and of all nested profiles.
You can limit recursion to one or more levels by
specifying a decimal integer as part of the -r option.
For example, -r 1 shows the elements of the specified
profile and, for element members that are profiles, the
command also shows their elements; then recursion stops.
Without the -r option, only the profile elements in the
specified entry are shown.
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using the
-u option bypasses the local cache, allowing rpccp to go
directly to a CDS server for the inquiry. rpccp then
updates the local CDS cache.
-v Indicates how a specified interface version is used
(optional). If it is used without the -i option, the
-v option is ignored. The possible combinations of
versions for the -v option and their actions are
described in the following table.
________________________________________________
Versions Action
________________________________________________
all The interface version is ignored.
exact Both the major and minor versions
must match the specified versions.
compatible The major version must match the
specified version, and the minor
version must be greater than or
equal to the specified version.
major_only The major version must match the
specified version; the minor ver-
sion is ignored.
upto The major version must be less than
or equal to that specified. If the
major versions are equal, the minor
version must be less than or equal
to that specified.
________________________________________________
If the -v option is absent, the command shows compatible
version numbers.
ARGUMENTS
profile-entry-name
Indicates the name of the target profile. For an entry
in the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The show profile command shows the elements of a profile in the name
service database. The entry name of the profile is required.
By default, all elements in the profile are shown. You can select
a subset of the elements by specifying the -a, -i, or -m options.
The -r option enables you to show nested profiles.
Privilege Required
You need read permission to the CDS object entry (the target profile
entry). If you use the -r option, you also need read permission to
any nested profiles.
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following command operates from the system prompt to show the
cell profile /.:/cell-profile in the local cell:
$ rpccp show profile /.:/cell-profile
The initial DCL command sets up a logical name MOLLY_O_PROFILE,
which represents the user profile /.:/LandS/anthro/molly_o_profile.
The control program commands start the control program and show the
user profile associated with the MOLLY_O_PROFILE logical name, as
follows:
$ define MOLLY_O_PROFILE "/.:/LandS/anthro/molly_o_profile"
$ rpccp
rpccp> show profile MOLLY_O_PROFILE
RELATED INFORMATION
Commands: add element
remove element
remove profile
8.1.18 – show_server
NAME
show server - Shows the binding information, interface identifiers,
and object UUIDs in a server entry
SYNOPSIS
rpccp show server server-entry-name [-i [if-id]]
[-o [object-uuid]] [-s syntax] [-u]
OPTIONS
-i Shows interface identifiers from binding information
found in the entry (optional). Without the -i option,
the command displays all interface identifiers.
To display a specific interface, supply its identifier
as the value. The value has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-o Shows object UUIDs found in the entry (optional).
Without the -o option, the command displays all object
UUIDs. To display a specific object UUID, supply its
string representation as the value, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
-u Updates the local CDS cache copy of name service data
(optional). Name service data is cached locally on each
machine in a cell. If an rpccp inquiry can be satisfied
by data in the local CDS cache, this cached data is
returned. Locally cached copies of name service data
might not include a recent CDS update, however. If the
required data is not available in the local CDS cache,
rpccp goes to a CDS server(s) to retrieve the required
data. rpccp then updates the local CDS cache. Using
the -u option bypasses the local cache, allowing rpccp
to go directly to a CDS server for the inquiry. rpccp
then updates the local CDS cache.
ARGUMENTS
server-entry-name
Indicates the name of the target server. For an entry in
the local cell, you can omit the cell name and specify
only the cell-relative name.
DESCRIPTION
The show server command shows the RPC binding information, interface
identifiers, and object UUIDs in a server entry. The entry name of
the server entry is required.
This operation shows all of the potential bindings for an interface.
By default, this command displays bindings for the specified version
of the interface and for upwardly compatible versions of the
interface. The -v option controls which versions are targeted by
this command.
Privilege Required
You need read permission to the CDS object entry (the target server
entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The following commands start the control program and show the server
entry /.:/LandS/anthro/Cal_host_2 in the local cell:
$ rpccp
rpccp> show server /.:/LandS/anthro/Cal_host_2
The following command operates from the system prompt to display
a specific object and interface from the server entry
/.:/LandS/anthro/Cal_host_2 in the local cell:
$ rpccp show server \
> /.:/LandS/anthro/Cal_host_2 \
> -o 16977538-e257-11c9-8dc0-08002b0f4528 \
> -i ec1eeb60-5943-11c9-a309-08002b102989,1.1
RELATED INFORMATION
Commands: export
import
unexport
8.1.19 – unexport
NAME
unexport - Removes binding information, interface identifiers,
and object UUIDs from a server entry
SYNOPSIS
rpccp unexport entry-name {[-i if-id [-v versions]] |
[-o object-uuid]} [-s syntax]
OPTIONS
-i Defines an interface identifier to be unexported
(optional). Only one interface can be unexported in
a single operation. If specified, binding information
for this interface is removed from the entry. The -i
option can be qualified by the -v option. The value
has the following form:
interface-uuid,major-version.minor-version
The UUID is a hexadecimal string and the version numbers
are decimal strings, for example:
-i ec1eeb60-5943-11c9-a309-08002b102989,1.1
Leading zeros in version numbers are ignored.
-v Indicates how a specified interface version is used
(optional). If it is used without the -i option, the
-v option is ignored. The possible combinations of
versions for the -v option and their actions are
described in the following table.
Versions Action
________________________________________________
all The interface version is ignored.
exact Both the major and minor versions
must match the specified versions.
compatible The major version must match the
specified version, and the minor
version must be greater than or
equal to the specified version.
major_only The major version must match the
specified version; the minor ver-
sion is ignored.
upto The major version must be less than
or equal to that specified. If the
major versions are equal, the minor
version must be less than or equal
to that specified.
________________________________________________
If the -v option is absent, the command shows compatible
version numbers.
-o Defines an object to be unexported (optional). Each
unexport command accepts up to 32 -o options. The
UUID is a hexadecimal string, for example:
-o 3c6b8f60-5945-11c9-a236-08002b102989
-s Indicates the name syntax of the entry name (optional).
The only value for this option is the dce name syntax,
which is the default name syntax. Until an alternative
name syntax becomes available, specifying the -s option
is unnecessary.
ARGUMENTS
entry-name
Indicates the name of the target name service entry.
Usually, the target is a server entry. However, objects
also can be exported (without an interface identifier or
binding information) to a group or a profile.
For an entry in the local cell, you can omit the cell name
and specify only the cell-relative name.
DESCRIPTION
The unexport command removes binding information and an interface
identifier, object UUIDs, or both from a server entry, or it removes
object UUIDs from a group's entry. The command requires the entry
name and either the interface identifier or one or more object
UUIDs.
By default, the unexport operation removes compatible interface
versions.
Privilege Required
You need both read permission and write permission to the CDS object
entry (the target name service entry).
NOTE
This command is replaced at Revision 1.1 by the dcecp command and
may not be provided in future releases of DCE.
EXAMPLES
The initial DCL command sets up a logical name Calendar_1_1,
which represents the interface identifier of an RPC interface.
The control program commands start the control program and
remove (unexport) the Calendar Version 1.1 interface from the
server entry /.:/LandS/anthro/Cal_host_2 in the local cell, as
follows:
$ define Calendar_1_1 "ec1eeb60-5943-11c9-a309-08002b102989,1.1"
$ rpccp
rpccp> unexport \
> -i Calendar_1_1 \
> /.:/LandS/anthro/Cal_host_2
rpccp>
RELATED INFORMATION
Commands: export
import
show server
8.2 – Environmental Influences on Command Syntax
Environmental Influences on Command Syntax
There are variations in the action of the control program, depending
on whether commands are entered from the system prompt or from within
the control program. For example, entering the annotation field of
profile elements from the system prompt allows you to include internal
spaces in an annotation.
Function At System Prompt Inside Control Program
_______________________________________________________________
Strings within quotation Supported Not required
marks
Wildcard substitution Supported Unsupported
_______________________________________________________________
Some UNIX systems require that you place an escape symbol (\) before
string binding delimiters such as brackets ([ ]) or that you place
the delimiters within quotation marks (' ' or " ") at the system
prompt.
8.3 – Scope of the RPC Control Program Commands
The following table describes the scope of the RPC control program
commands.
Scope Command
_____________________________
All entries add entry
remove entry
show entry
Server entry export
import
show server
unexport
Group add member
remove group
remove member
show group
Profile add element
remove element
remove profile
show profile
Endpoint map add mapping
remove mapping
show mapping
_____________________________
8.4 – Logical Names
The control program supports logical names. Using logical names
facilitates interactive use of the control program.
To distinguish logical names, rpccp* reference pages follow the
convention of using all uppercase letters for examples of logical
names. Note that OpenVMS logical names are NOT case sensitive.
User-defined logical names
You can set a logical name to represent values to rpccp.
Using a logical name is helpful for specifying a long string
such as the following:
+ A string representation of binding information (binding
string)
+ A string representation of an object or interface UUID
(string UUID)
+ An interface identifier (the interface UUID and version
numbers)
+ The name of a name service entry
For example, in the following example, the logical name
JANE_CAL represents an object UUID; the target name service
entry, /.:/LandS/anthro/Cal_host_2, is in the local cell:
$ DEFINE JANE_CAL 47f40d10-e2e0-11c9-bb29-08002b0f4528
$ rpccp
rpccp> export -o JANE_CAL /.:/LandS/anthro/Cal_host_2
DCE RPC logical names
The dce name syntax is the only syntax currently supported
by the DCE Cell Directory Service (CDS). However, the Name
Service Interface (NSI) is independent of any specific name
service and, in the future, may support name services that
use other name syntaxes. When alternative name syntaxes are
supported, you can override the standard default with a
process-specific default by setting the
RPC_DEFAULT_ENTRY_SYNTAX logical name. When this variable is
set for a process, the control program uses it to find out the
default syntax for the process. You can override this default
in any NSI command of the control program by using the -s
option to specify an alternative entry syntax. Setting
RPC_DEFAULT_ENTRY_SYNTAX requires specifying the integer 3 to
indicate the dce syntax. To set RPC_DEFAULT_ENTRY_SYNTAX, use
the name=value command to define a logical name. The following
command specifies dce as the default name syntax in a login
command file:
# .login command file
# setting dce as default name syntax,
RPC_DEFAULT_ENTRY_SYNTAX=3
RPC_DEFAULT_ENTRY
For the import command, you can use this environment
variable to indicate the entry where the search operation
starts. Usually, the starting entry is a profile.
8.5 – Name Service Interface
The remainder of this description contains information to help you use commands that call the name service interface to access name service entries (NSI commands). The DCE RPC name service interface (NSI) is independent of any particular name service. CDS, however, is the only name service available for DCE RPC Version 1.0 applications. For more details on the name service interface, see the OSF DCE Application Development Guide-Core Components. For a description of the DCE Cell Directory Service, see the OSF DCE Administration Guide-Core Components.
8.5.1 – Name Service Entries
To store information about RPC servers, interfaces, and objects, the
NSI defines the following name service entries:
server entry
Stores binding information, interface identifiers, and
object UUIDs for an RPC server.
group Corresponds to one or more RPC servers that offer a common
RPC interface, type of RPC object, or both.
profile Defines search paths for looking in a name service
database for a server that offers a particular RPC
interface and object.
Note that when the NSI is used with the Cell Directory Service, the
name service entries are CDS object entries.
8.5.2 – Structure of Entry Names
Each entry in a name service database is identified by a unique
global name made up of a cell name and a cell-relative name.
A cell is a group of users, systems, and resources that share common
DCE services. A cell configuration includes at least one cell
directory server, one security server, and one time server.A cell's
size can range from one system to thousands of systems. For
information on cells, see the CDS portion of this book.
The following is an example of a global name:
/.../C=US/O=uw/OU=MadCity/LandS/anthro/Stats_host_2
The parts of a global name are as follows:
Cell name (using X.500 name syntax)
For example:
/.../C=US/O=uw/OU=MadCity
The symbol /... begins a cell name. The letters before
the equal signs (=) are abbreviations for country (C),
organization (O), and organization unit (OU).
For entries in the local cell, the cell name can be
represented by a /.: prefix, in place of the actual cell
name; for example,
/.:/LandS/anthro/Stats_host_2
For NSI operations on entries in the local cell you can
omit the cell name.
Cell-relative name
Each name service entry requires a cell-relative name,
which contains a directory pathname and a leaf name.
directory pathname
Follows the cell name and indicates the
hierarchical relationship of the entry to the
cell root. The directory pathname is the middle
portion of the global name. The cell name is to
the left of the directory pathname, and the leaf
name is to the right, as follows:
cell-name + directory-pathname + leaf-name
The directory pathname contains the names of any
subdirectories in the path; each subdirectory
name begins with a slash (/), as follows:
/sub-dir-a-name/sub-dir-b-name/sub-dir-c-name
Directory paths are created by name service
administrators. If an appropriate directory path
does not exist, ask your name service
administrator to extend an existing path or
create a new path. In a directory path, the
name of a subdirectory should reflect its
relationship to its parent directory (the
directory that contains the subdirectory).
leaf name Identifies the specific entry. The leaf name is
the right-hand part of global name beginning
with the rightmost slash.
In the following example, /.../C=US/O=uw/OU=MadCity is the cell
name, /LandS/anthro is the directory pathname, and /Cal_host_4 is
the leaf name.
/.../C=US/O=uw/OU=MadCity/LandS/anthro/Cal_host_4,
If a name service entry is located at the cell root, the leaf name
directly follows the cell name; for example, /.:/cell-profile.
Note that when the NSI is used with CDS, the cell-relative name is a
CDS name.
8.5.3 – Guidelines for Constructing 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. The cell name is
assigned to a cell root at its creation. When you specify only a
cell-relative name to an NSI command, the NSI automatically expands
the name into a global name by inserting the local cell name. When
returning the name of a name service entry, a group member, or
member in a profile element, NSI operations return global names.
The directory pathname and leaf name uniquely identify a name
service entry. The leaf name should somehow describe the entry;
for example, by identifying its owner or its contents.The remainder
of this section contains guidelines for choosing leaf names.
Note that directory pathnames and leaf names are case sensitive.
Naming a Server Entry
For a server entry that advertises an RPC interface or service
offered by a server, the leaf name must distinguish the entry
from the equivalent entries of other servers. When a single
server instance runs on a host, you can ensure a unique name
by combining the name of the service, interface (from the
interface definition), or the system name for the server's
host system.
For example, consider two servers, one offering a calendar
service on host JULES and one, on host VERNE.
The server on JULES uses the following leaf name:
calendar_JULES
The server on VERNE uses the following leaf name:
calendar_VERNE
For servers that perform tasks on or for a specific system, an
alternative approach is to create server entries in a system-
specific host directory within the name service database. Each
host directory takes the name of the host to which it
corresponds. Because the directory name identifies the
system,the leaf name of the server entry name need not include
the host name, for example:
/.:/LandS/host_1/Process_control
To construct names for the server entries used by distinctive
server instances on a single host, you can construct unique
server entry names by combining the following information: the
name of the server's service, interface, or object; the system
name of the server's host system, and a reusable instance
identifier, such as an integer.
For example,the following leaf names distinguish two instances
of a calendar service on the JULES system:
calendar_JULES_01
calendar_JULES_02
Avoid automatically generating entry names for the server
entries of server instances, for example, by using unique
data such as a time stamp (calendar_verne_15OCT91_21:25:32)
or a process identifier (calendar_jules_208004D6). When a
server incorporates such unique data into its server entry
names, each server instance creates a separate server entry,
causing many server entries. When a server instance stops
running, it leaves an obsolete server entry that is not
reused. The creation of a new entry whenever a server
instance starts may impair performance. A server can use
multiple server entries to advertise different combinations
of interfaces and objects. For example, a server can create
a separate server entry for a specific object (and the
associated interfaces). The name of such a server entry
should correspond to a well-known name for the object. For
example,consider a server that offers a horticulture
bulletin board known to users as horticulture_bb. The
server exports th horticulture_bb object, binding informa-
tion, and the associated bulletin-board interface to a server
entry whose leaf name identifies the object, as follows:
horticulture_bb
Note that an RPC server that uses RPC authentication can
choose identical names for its principal name and its server
entry. Use of identical names permits a client that calls the
rpc_binding_set_auth_info routine to automatically determine a
server's principal name (the client will assume the principal
name to be the same as the server's entry name). If a server
uses different principal and server entry names, users must
explicitly supply the principal name. For an explanation of
principal names, see the DCE Security Service part of the DCE
Application Development Guide.
Naming a Group
The leaf name of a group should indicate the interface,
service,or object that determines membership in the group.
For example, for a group whose members are selected because
they advertise an interface named Statistics, the following is
an effective leaf name:
Statistics
For a group whose members advertise laser-printer print queues
as objects, the following is an effective leaf name:
laser-printer
Naming a Profile
The leaf name of a profile should indicate the profile users;
for example, for a profile that serves the members of an
accounting department, the following is an effective leaf
name:
accounting_profile
8.5.4 – Permissions Required
To use the NSI commands to access entries in a 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.
Note that write permission does not imply read permission.
ACL permissions for the NSI commands of the control program are
described in the reference pages.
8.6 – EXAMPLES
The following command starts the RPC control program:
$ rpccp
rpccp>
The following command at the system prompt removes the entry
/.:/LandS/anthro/Cal_host_2:
$ rpccp remove entry \
> /.:/LandS/anthro/Cal_host_2
9 – rpcd
NAME
rpcd - DCE Remote Procedure Call Daemon
DESCRIPTION
The DCE Remote Procedure Call Daemon (RPCD) has been replaced
by the DCE Daemon (DCED) as of OSF DCE Version 1.1.
RELATED_INFORMATION
See "DCE dce_tools_intro dced" for a descripton of the new DCE
daemon.