wchar_t_to_netcs(3rpc)
Converts international character data from a local code set to a network code set prior to marshalling; 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.
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. NULL is specified if a fixed or varying 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.
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 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 idl_byte format. If the data is a conformant or conformant varying array, the routine also returns the length of the converted data, in units of idl_byte.
Prior to calling wchar_t_to_netcs( ), client and server stubs call the wchar_t_net_size( ) routine to calculate the size of the buffer required to hold the converted data. Because wchar_t_net_size( ) cannot make this calculation for fixed and varying arrays, applications should either restrict use of wchar_t_to_netcs( ) to conformant and conformant varying arrays, or independently ensure that the buffer allocated for converted data is large enough.
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.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_ss_incompatible codesets
The binding handle does not contain code set evaluation information. 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
When invoked from the server stub, the routine calls the dce_cs_loc_to_rgy( ) routine and host converter routines. If any of these routines return an error, an exception is raised to the client application.
Related Information
Functions: cs_byte_from_netcs(3rpc)