NAME

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

SYNOPSIS

#include <dce/codesets_stub.h>

void cs_byte_to_netcs(
	rpc_binding_handle_t binding,
	unsigned32 network_code_set_value,
	idl_byte *local_data,
	unsigned32 local_data_length,
	idl_byte *network_data,
	unsigned32 *network_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 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_data

A pointer to the international character data to be transmitted.

local_data_length

The number of cs_byte data elements to be converted. For a varying array or a conformant varying array, this value is the local value of the length_is variable. For a conformant array, this 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.

Output

network_data

A pointer to the converted data, in idl_byte format.

network_data_length

The length of the converted data, in units of idl_byte. 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 cs_byte_to_netcs() routine converts 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 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.

Applications do not call the cs_byte_to_netcs() routine directly; client and server stubs can call the routine before they marshall data that is to be transmitted over the network. The routine compares the network (receiving) 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 idl_byte format. If the data is a conformant or conformant varying array, the routine also returns the length of the converted data.

When invoked from the server stub, the routine calls the dce_cs_loc_to_rgy() routine 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 support code set conversion for this local data type as required.

Permissions Required

None.

RETURN VALUE

None.

SEE ALSO

cs_byte_from_netcs()
cs_byte_local_size()
cs_byte_net_size()
dce_cs_loc_to_rgy()
wchar_t_from_netcs()
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.