NAME

dce_cs_rgy_to_loc- maps a code set value in the code set registry to the local name for a code set

SYNOPSIS

#include <dce/rpc.h>

void dce_cs_rgy_to_loc(
	unsigned32 *rgy_code_set_value,
	idl_char **local_code_set_name,
	unsigned16 *rgy_char_sets_number,
	unsigned16 **rgy_char_sets_value,
	error_status_t *status);

PARAMETERS

Input

rgy_code_set_value

The registered hexadecimal value that uniquely identifies the code set.

Output

local_code_set_name

A string that specifies the name used by the local host's locale environment to refer to the code set specified by rgy_code_set_value. The string is a maximum of 32 bytes (31 character data bytes and a terminating NULL character).

rgy_char_sets_number

The number of character sets that the specified code set encodes. Specifying NULL prevents the routine from returning this argument.

rgy_char_sets_value

A pointer to an array of registered integer values that uniquely identify the character set(s) that the specified code set encodes. Specifying NULL in this argument prevents the routine from returning this argument. The routine dynamically allocates this value.

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:

dce_cs_c_ok

Code set registry access succeeded.

dce_cs_c_cannot_allocate_memory

Cannot allocate memory for code set info

dce_cs_c_cannot_open_file

Cannot open the code set registry file

dce_cs_c_cannot_read_file

Cannot read the code set registry file

dce_cs_c_unknown

Value not found in the code set registry

dce_cs_c_not_found

No local code set name exists in the code set registry

DESCRIPTION

The dce_cs_rgy_to_loc() routine maps a unique identifier for a character/code set encoding in the code set registry to its operating system-specific (local) name. 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.

If no local_code_set_name can be obtained from the registry, the routine returns the status dce_cs_c_unknown and an undefined string.

Specifying NULL in the rgy_char_sets_number and rgy_char_sets_value arguments prevents the routine from performing the additional search for these values. If the rgy_char_sets_value value is returned by the routine, the application should free the rgy_char_sets_value array after it is used.

The code sets compatibility evaluation routines rpc_cs_eval_with_universal(), rpc_cs_eval_without_universal(), and rpc_cs_character_set_compat_check() use the dce_cs_rgy_to_loc() routine to ensure that the server supports a character set that is compatible with the client. The stub support code set conversion routines cs_byte_from_netcs(, cs_byte_to_netcs(, wchar_t_from_netcs(, and wchar_t_to_netcs( use this routine to obtain the string name that matches the name of the host code set converter that they will call to perform a code set conversion.

In general, applications that transfer international characters do not need to call this routine directly. However, any further code set conversion implementations may need to call this routine in order to make code set comparisons and identify the appropriate local code set.

Permissions Required

None.

RETURN VALUE

None.

SEE ALSO

cs_byte_from_netcs()
cs_byte_local_size()
cs_byte_net_size()
cs_byte_to_netcs()
dce_cs_loc_to_rgy()
rpc_cs_char_set_compat_check()
rpc_cs_eval_with_universal()
rpc_cs_eval_without_universal()
rpc_rgy_get_code_sets()
wchar_t_from_netcs()
wchar_t_local_size()
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.