cs_byte_local_size(3rpc)
Calculates the necessary buffer size for code set conversion from a network code set to a local code set prior to unmarshalling; used by client and server stubs but not directly by 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.
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 cs_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.
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 four 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 cs_byte_*_size routines when the cs_byte type (which is internally equivalent to idl_byte) has been specified as the local data type using the cs_char attribute in the attribute configuration file for the application. The cs_byte_local_size( ) routine is used to evaluate buffer size requirements prior to unmarshalling data received over the network.
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 set's 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 maximum number of bytes required to represent 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 idl_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. If a conformant or conformant varying array is to be unmarshalled, the routine also returns the value of network_buffer_size in local_buffer_size.
In cases in which the binding handle does not contain the results of character and code sets evaluation, or in which the cs_byte_local_size( ) routine is being called from the server stub, it 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, it also calculates the size of this new buffer (by multiplying the value of network_buffer_size by the maximum number of bytes required to represent the code set specified in network_code_set_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.
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 the information necessary to evaluate the code set. 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.
Related Information
Functions: cs_byte_from_netcs(3rpc)