NAME

wchar_t_from_netcs- converts international character data from a network code set to a local code set

SYNOPSIS

#include <dce/codesets_stub.h>

void wchar_t_from_netcs(
	rpc_binding_handle_t binding,
	unsigned32 network_code_set_value,
	idl_byte *network_data,
	unsigned32 network_data_length,
	unsigned32 local_buffer_size,
	wchar_t *local_data,
	unsigned32 *local_data_length,
	error_status_t *status);

PARAMETERS

Input

binding

Specifies the target binding handle from which to obtain code set conversion 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_data

A pointer to the international character data that has been received, in the network code set encoding.

network_data_length

The number of idl_byte data elements to be converted. For a varying array or a conformant varying array, the value is the local value of the length_is variable. For a conformant array, the value is the local value of the size_is variable. For a fixed array, the value is the array size specified in the interface definition.

local_buffer_size

A pointer to the buffer size to be allocated to contain the converted data, in units of wchar_t. The value specified in this argument is the local buffer size returned by the wchar_t_local_size() routine.

Output

local_data

A pointer to the converted data, in wchar_t format.

local_data_length

The length of the converted data, in units of wchar_t. Specify NULL if a fixed or varying array is to be converted.

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.

When running the host converter, the following errors can occur:

rpc_s_ss_invalid_char_input

Invalid character input for conversion.

rpc_s_ss_short_conv_buffer

Buffer not large enough for converted characters.

DESCRIPTION

The wchar_t_from_netcs() routine converts 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.

Applications do not call the wchar_t_from_netcs() routine directly; client and server stubs can call the routine before they unmarshall data received from the network. The routine compares the network (sending) code set to the local code set currently in use; if it finds that code set conversion is necessary, it determines which host code set converter to call to convert the data and then invokes that converter.

The routine then returns the converted data in wchar_t format. If the data is a conformant or conformant varying array, the routine also returns the length of the converted data.

When invoked by the server, the routine calls dce_cs_loc_to_rgy() and the host converter routines. If these routines return an error, an exception is raised to the client application.

An application can specify a local data type other than cs_byte and wchar_t (the local data types for which code set conversion is implemented). In this case, the application must also supply code set conversion for this local data type as required.

Prior to calling wchar_t_from_netcs() client and server stubs call the wchar_t_local_size() routine to calculate the size of the buffer required to hold the converted data. Because wchar_t_local_size() cannot make this calculation for fixed and varying arrays, applications should either restrict use of wchar_t_from_netcs() to conformant and conformant varying arrays, or independently ensure that the buffer allocated for converted data is large enough.

Permissions Required

None.

RETURN VALUE

None.

SEE ALSO

cs_byte_from_netcs()
cs_byte_to_netcs()
dce_cs_loc_to_rgy()
wchar_t_to_netcs()
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.