NAME

   wchar_t_from_netcs - Converts international character data from a
                        network code set to a local code set

   Used by client and server applications.

 SYNOPSIS

   #include <dce/codesets_stub.h>

   void wchar_t_from_netcs( rpc_binding_handle_t binding,
                            unsigned32 network_code_set_value,
                            idl_byte *network_data,
                            unsigned32 network_data_length,
                            unsigned32 local_buffer_size,
                            wchar_t *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.
       When called from the server stub, this value is a pointer to
       binding information that the client stub passed in the RPC call.

   network_code_set_value
       The registered hexadecimal integer value that represents the code
       set that was used to transmit 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 the network code set encoding.

   network_data_length
       The number of byte data elements to be converted. This is the
       size of the byte string that was sent through the network.

   local_buffer_size
       A pointer to the buffer size to be allocated to contain the
       converted data, in units of wchar_t. The value specified in
       this parameter is the local buffer size returned by the
       wchar_t_local_size() routine.

   Output

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

   local_data_length
       The length of the converted data, in units of wchar_t.  Specify
       NULL if a fixed 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.  The possible status codes and their meanings are as
       follows:

       rpc_s_ok       Success.

       rpc_s_ss_incompatible_codesets
                      The specified code set does not match the code set
                      specified in the sending tag in the binding handle.
                      If this error occurs in the server stub, an
                      exception is raised to the client application.

   When the routine is running the host converter routines, the following
   errors can be returned:

       rpc_s_ss_invalid_char_support

       rpc_s_ss_short_conv_buffer

       rpc_s_ss_iconv_error (HP-UX reference platform only)

       rpc_s_ss_no_memory (HP-UX reference platform only)

   When invoked from the server stub, this routine calls the
   dce_cs_loc_to_rgy() routine and the host converter routines.  If
   one of these routines returns an error, an exception is raised to
   the client application.

 DESCRIPTION

   The wchar_t_from_netcs() routine belongs to a set of DCE RPC routines
   for use by client and server applications that are transferring
   international character data in a heterogeneous character set and code
   sets environment.

   The wchar_t_from_netcs() routine is one of the DCE RPC stub code set
   conversion routines that RPC stubs use before they marshall or
   unmarshall data to convert international character data to and from
   local and network code sets.

   Client and server stubs call the wchar_t_*_netcs routines when the
   wchar_t type has been specified as the local data type using the
   cs_char attribute in the attribute configuration file for the
   application.

   Client and server stubs call the wchar_t_from_netcs() routine before
   they unmarshall the international character data received from the
   network.  The routine takes a binding handle, a code set value that
   identifies the code set used to transfer international character data
   over the network, the address of the network data, in idl_byte format,
   that may need to be converted, and the data length, in units of
   idl_byte.

   The routine compares the sending code set to the local code set
   currently in use. If the routine finds that code set conversion is
   necessary, (because the local code set differs from the code set
   specified to be used on the network), 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 wchar_t format.  If
   the data is a varying, conformant, or conformant varying array, the
   routine also returns the length of the converted data, in units of
   wchar_t.

   Applications can specify local data types other than cs_byte and
   wchar_t (the local data types for which DCE RPC supplies stub code
   set conversion routines) with the cs_char ACF attribute. In this
   case, the application must also supply local_type_to_netcs() and
   local_type_from_netcs() stub conversion routines for this type.

   Permissions Required

   No permissions are required.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: cs_byte_from_netcs
              cs_byte_to_netcs
              wchar_t_to_netcs