When RPC clients and servers exchange international character data, the data being exchanged needs to be understood by both client and server. Both client and server need to understand a character set, and both client and server need to understand the way that character set is expressed. Code set conversion provides a way for a character set to be represented in a form that both client and server can understand, given that the client and server are using a compatible character set. (In general, character set conversion is not recommended; it is unlikely that clients and servers would want to map, for example, German characters to Chinese characters due to the data loss that would occur as a result.)
The stub support routines for code set conversion provide the mechanism for the stubs to use to convert between different code sets, given that character set compatibility has been established. The code set conversion routines translate a character set from one encoding to another. Consequently, the code set conversion routines provide the way for a character set to be represented in a form that both client and server can understand.
You must provide the following code set conversion routines for each local type that you define with the cs_char attribute:
· local_type_name_to_netcs( ) - Converts international character data from a local code set to a network code set. Client and server stubs call this routine before they marshal any international character data.
· local_type_name_from_netcs( ) - Converts international character data from a network code set to a local code set. Client and server stubs call this routine before they unmarshal any international character data.
You specify the name for the local data type in the local_type_name portion of the function name and the appropriate suffix name _to_netcs or _from_netcs.
DCE RPC provides code set conversion routines for the cs_byte and wchar_t data types. These routines are:
· cs_byte_to_netcs( ) - Converts international character data from a local code set to a network code set when the cs_byte type has been specified as the local data type in the .acf file.
· cs_byte_from_netcs( ) - Converts international character data from a network code set to a local code set when the cs_byte type has been specified as the local data type in the .acf file.
· wchar_t_to_netcs( ) - Converts international character data from a local code set to a network code set when the wchar_t data type has been specified as the local data type in the .acf file.
· wchar_t_from_netcs( ) - Converts international character data from a network code set to a local code set when the wchar_t data type has been specified as the local data type in the .acf file.
If your application uses either of these data types as the local type, it can use these DCE RPC code set conversion routines; in order to do so, simply link with the DCE library when compiling your application. Refer to the cs_byte_*(3rpc) and wchar_t_*(3rpc) reference pages in the OSF DCE Application Development Reference for a description of the cs_byte_ and wchar_t_ routine signatures and functions.
Applications that use data types other than cs_byte or wchar_t as their local data types will need to provide their own code set conversion routines. User-provided code set conversion routines must follow the same signature as the DCE RPC-provided code set conversion routines. See the cs_byte_*(3rpc) and wchar_t_*(3rpc) reference pages in the OSF DCE Application Development Reference for a description of the cs_byte_ and wchar_t_ routine signatures and functions.
The DCE code set conversion routines depend upon the presence of the XPG4 iconv code set conversion facility in the underlying operating system platform. The iconv facility consists of the following routines:
· iconv_open( ) - Code conversion allocation function; returns a conversion descriptor that describes a conversion from the code set specified in one string pointer argument to the code set specified in another string pointer argument.
· iconv( ) - Code conversion function; converts the sequence of characters from one code set into a sequence of corresponding characters in another code set.
· iconv_close( ) - Code conversion deallocation function; deallocates the conversion descriptor and all associated resources allocated by the iconv_open( ) function.
Note that the iconv facility identifies a code set by a string name. This string name is the name that the local platform uses to refer to the code set. However, all of the stub support routines for automatic code set conversion use the unique identifier assigned to the code set in the code set registry to identify a code set. Before the DCE code set conversion routines can invoke the iconv facility, they must access the code set registry to retrieve the platform-specific string names associated with the local and network code set identifiers.
The DCE code set conversion routines use the dce_cs_loc_to_rgy( ) and dce_cs_rgy_to_loc( ) routines to access the code set registry and translate between code set string names and their corresponding unique identifiers. The OSF DCE Application Development Reference provides a description of these routines' signatures and functions; developers who are writing their own code set conversion routines and who are using the iconv facility for conversion may want to use these DCE routines to convert between code set names and identifiers.