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