NAME

cs_byte_net_size- calculates the necessary buffer size for conversion of international character data from a local code set to a network code set

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.

network_code_set_value

The registered hexadecimal integer value that represents the code set to be used to transmit the 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 cs_byte, 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. 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 nonNULL only if a conformant or conformant varying array is to be marshalled. A value of NULL in this argument 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.

Possible status codes and their meanings include:

rpc_s_ok

Success.

rpc_s_ss_incompatible_codesets

Conversion between code sets not possible.

If this error occurs in the server stub, an exception is raised to the client application.

DESCRIPTION

The cs_byte_net_size() routine calculates the necessary buffer size for the conversion of international character data from a local code set to a network code set when cs_byte has been specified as the local data type. (The cs_byte type is internally equivalent to the idl_byte type.) The routine is one of those used for character and code set interoperability, which permits clients and servers to transfer international character data in a heterogeneous character set and code sets environment.

The routine determines the type of conversion required and calculates the size of the necessary buffer, if a conformant or conformant varying array is to be marshalled; the calling stub then allocates a buffer of that size before it calls one of the code set conversion routines.

Applications do not call the cs_byte_net_size() routine directly; client and server stubs can call the routine before they marshall any data. When called from a client stub, the routine determines the value of conversion_type from client and server code set tag information stored in the binding handle by a code sets evaluation or tag-setting routine. If the conversion type specified in the handle is idl_cs_new_buffer_convert, the routine sets the conversion_type argument 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 maximum number of bytes required to represent the code set specified by network_code_set_value. The routine returns the new buffer size in the network_buffer_size argument. The size is specified in units of idl_byte, which is the network representation used for international character data (and is internally equivalent to the cs_byte type). For fixed and varying arrays, the routine assumes that local_buffer_size is sufficient to store the converted data.

If the binding 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 argument. If a conformant or conformant varying array is to be marshalled, the routine also returns the value of local_buffer_size in network_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_net_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 argument, 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, it also calculates the size of this new buffer (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) and returns the results, in units of idl_byte, in network_buffer_size.

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_net_size() routine raises an exception to the client application.

Permissions Required

None.

RETURN VALUE

None.

SEE ALSO

cs_byte_from_netcs()
cs_byte_local_size()
cs_byte_to_netcs()
dce_cs_loc_to_rgy()
rpc_rgy_get_max_bytes()
wchar_t_local_size()
wchar_t_net_size().

Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.