The interface definition file is where the set of remote operations that constitute the interface are defined. The first step in writing an interface definition file that supports automatic code set conversion is to create a special typedef that, when used in operation parameters, represents international character data that can be automatically converted, if necessary, before marshalling and unmarshalling at client and server sites.
As described in The byte Type, the data representation for a byte data type is guaranteed not to change when the data is transmitted by the RPC communications protocol. Consequently, the special international character data type defined in the .idl is always declared to be a byte type so that the RPC protocol will not automatically treat it as a DCE PCS character and convert it between ASCII and EBCDIC.
The second step in writing an interface definition file that supports automatic code set conversion is to define, for each operation that will transmit the special international character data type, a maximum of three operation parameters that will tag the international characters being passed in the operation's input and output parameters with code set identifying information established during the client-server evaluation and binding procedure. These parameters are:
· The sending tag, which indicates the code set the client is using for international characters it transmits over the network. The sending tag has the in parameter attribute, and is applied to international character data declared in the operation's input parameters. If the operation does not specify any international character data as input, then it is not necessary to create this parameter.
· The desired receiving tag, which indicates the code set in which the client prefers to receive international character data sent back from the server as output. The desired receiving tag has the in parameter attribute. If the operation does not specify any international character output data, then it is not necessary to create this parameter.
· The receiving tag, which indicates the code set the server is using for international characters it transmits over the network. The receiving tag has the out parameter attribute, and is applied to international character data declared in the operation's output parameters. If the operation does not specify any international character output data, then it is not necessary to create this parameter.
You must define these code set tag parameters as unsigned long integers or unsigned long integers passed by reference. The receiving tag parameter must be declared as a pointer to the receiving tag unsigned long integer.
When international character data is to be unmarshalled, the client or server stub needs to have received a description of the code set being used before it receives the data. For this reason, the sending tag parameter must occur in an operation's parameter list before any in international character data, and the receiving tag parameter must occur in an operation's parameter list before any out international character data. The requirement that a tag must be received before the data it relates to is received also means that a customized binding handle cannot include international characters. This is because a binding handle must be the first parameter in a parameter list.
Here is an example .idl file for an interface named cs_test that uses the special international character type definition and the code set tag parameters for input and output parameters that are fixed arrays of characters from an international character set:
[
uuid(b076a320-4d8f-11cd-b453-08000925d3fe),
version(1.0)
]
interface cs_test
{
const unsigned short SIZE = 100;
typedef byte net_byte;
error_status_t cs_fixed_trans (
[in] handle_t IDL_handle,
[in] unsigned long stag,
[in] unsigned long drtag,
[out] unsigned long *p_rtag,
[in] net_byte in_string[SIZE],
[out] net_byte out_string[SIZE]
);