NAME

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

SYNOPSIS

#include <dce/codesets_stub.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.

network_code_set_value

The registered hexadecimal integer value that represents the code set 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 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. Because wchar_t and idl_byte require different numbers of bytes to encode one character, and idl_byte to wchar_t conversion always takes place, the conversion type returned is always idl_cs_new_buffer_convert.

local_buffer_size

A pointer to the buffer size that must be allocated to contain the converted data, in units of wchar_t. This value is used as the local value of the size_is variable for the array, and is nonNULL only if a conformant or conformant varying array is to be unmarshalled. A value of NULL 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.

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 wchar_t_local_size() routine calculates the necessary buffer size for the conversion of international character data from a network code set to a local code set when wchar_t has been specified as the local data 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 wchar_t_local_size() 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 unmarshalled; 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 wchar_t_local_size() routine directly; client and server stubs can call the routine before they unmarshall any data. Because wchar_t and idl_byte require different numbers of bytes to encode one character, wchar_t_local_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 unmarshalled, the routine then 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 argument. The size is specified in units of wchar_t, which is the local representation used for international character data in wide character format.

When a fixed or varying array is being unmarshalled, the wchar_t_local_size() routine cannot calculate the required buffer size and does not return a value in the local_buffer_size argument.

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.

Permissions Required

None.

RETURN VALUE

None.

SEE ALSO

cs_byte_local_size()
cs_byte_net_size()
dce_cs_loc_to_rgy()
rpc_rgy_get_max_bytes()
wchar_t_from_netcs()
wchar_t_net_size()
wchar_t_to_netcs().

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.