Previous section.

CDE 1.1: Remote Procedure Call
Copyright © 1997 The Open Group

NAME

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

SYNOPSIS

#include <dce/codesets_stub.h>

void cs_byte_from_netcs( rpc_binding_handle_t binding, unsigned32 network_code_set_value, idl_byte *network_data, unsigned32 network_data_length, unsigned32 local_buffer_size, idl_byte *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 network code set encoding.

network_data_length
The number of idl_byte data units 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.

local_buffer_size
A pointer to the buffer size to be allocated to contain the converted data, in units of cs_byte. The value specified in this argument is the local buffer size returned from the cs_byte_local_size() routine.

Output

local_data
A pointer to the converted data, in cs_byte format.

local_data_length
The length of the converted data, in units of cs_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_from_netcs() routine converts international character data from a network code set to a local code set when cs_byte has been specified as the local data type. (The cs_byte type is equivalent to the 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_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 cs_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_local_size()
cs_byte_net_size()
cs_byte_to_netcs()
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.

Contents Next section Index