wchar_t_net_size(3rpc)
Calculates the necessary buffer size for code set conversion from a local code set to a network code set prior to marshalling; used by client and server stubs but not directly by 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.
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. For a conformant or conformant varying array,
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 idl_byte require different numbers of bytes to encode one character, and wchar_t to
idl_byte conversion always takes place, the conversion type returned is always idl_cs_new_buffer_convert.
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.
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 or unmarshalled); 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 two wchar_t_*_size 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. The wchar_t_net_size( ) routine is used to evaluate buffer size requirements prior to marshalling data to be sent over the network.
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.
Because wchar_t and idl_byte require different numbers of bytes to encode one character, wchar_t_net_size( ) always sets conversion_type to idl_cs_new_buffer_convert, regardless of whether it is called from a client or server stub, or whether client and server code set tag information has been stored in the binding handle by a code sets evaluation or tag-setting routine. If a conformant or conformant varying array is to be marshalled, the routine then calculates a new buffer size by dividing the value of local_buffer_size by the number of bytes required to encode one wchar_t unit. 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.
When a fixed or varying array is being marshalled, the wchar_t_net_size routine cannot calculate the required buffer size and does not return a value in the network_buffer_size argument.
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 invoked from the server stub, this routine calls the dce_cs_loc_to_rgy( ) and the rpc_rgy_get_max_bytes( ) routines. If either of these routines return an error, the wchar_t_net_size( ) routine raises an exception to the client application.
Related Information
Functions: cs_byte_local_size(3rpc)