These are the RPC application development routines.
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
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 – 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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
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.
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.
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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.
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
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
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
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
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
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
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.
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
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
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.
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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