NAME

   wchar_t_net_size - Calculates the necessary buffer size for code set
                      conversion from a local code set to a network code
                      set

   Used by client and server applications.

 SYNOPSIS

   #include <dce/rpc.h>

   void wchar_t_net_size( rpc_binding_handle_t binding,
                          unsigned32 network_code_set_value,
                          unsigned32 local_buffer_size,
                           idl_cs_convert_t *conversion_type,
                          unsigned32 *network_buffer_size,
                          error_status_t *status );

 PARAMETERS

   Input

   binding
       Specifies the target binding handle from which to obtain buffer
       size evaluation 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 infor mation that the client stub passed in
       the RPC call.

   network_code_set_value
       The registered hexadecimal integer value that represents the code
       set to be 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 sending tag.  When the caller is
       the server stub, this value is the receiving tag.

   local_buffer_size
       The size, in units of wchar_t, of the buffer that is allocated
       for the international character data.  This value is the local
       value of the size_is variable for the array; that is, the value
       is the size of the marshalled string if no conversion is done.

   Output

   conversion_type
       A pointer to the enumerated type defined in dce/idlbase.h that
       indicates whether data conversion is necessary and whether or
       not the existing buffer is sufficient for storing the results of
       the conversion.  Because wchar_t to cs_byte conversion always
       takes place, and because wchar_t and cs_byte are different units,
       the conversion type returned is always idl_cs_new_buffer_convert,
       which means that the converted data must be written to a new
       buffer.

   network_buffer_size
       A pointer to the buffer size that needs to be allocated to contain
       the converted data, in units of idl_byte. This value is to be used
       as the network value of the size_is variable for the array, and is
       non-NULL only if a conformant or conformant varying array is to be
       marshalled.  A value of NULL in this parameter indicates that a
       fixed or varying array is to be marshalled.

   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 invoked from the server stub, this routine calls the routines
   dcs_cs_loc_to_rgy() and rpc_rgy_get_max_bytes().  If either of these
   routines returns an error, the wchar_t_net_size() routine raises an
   exception to the client application.

 DESCRIPTION

   The wchar_t_net_size() 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_net_size() routine is one of the DCE RPC buffer sizing
   routines that RPC stubs use before they marshall or unmarshall data
   to determine whether or not the buffers allocated for code set
   conversion need to be enlarged to hold the converted data.  The
   buffer sizing routines determine the type of conversion required
   and calculate the size of the necessary buffer (if a conformant or
   conformant varying array is to be marshalled).  The RPC stub then
   allocates a buffer of that size before it calls one of the code set
   conversion routines.

   Client and server stubs call the wchar_t_*_size routines when the
   wchar_t type has been specified as the local data type with the
   cs_char attribute in the attribute configuration file for the
   application.  Applications do not call the wchar_t_net_size() routine
   directly.  Client and server stubs call the routine before they
   marshall any data.  The stubs pass the routine a binding handle and a
   code set value that identifies the code set to be used to transfer
   international character data over the network. The stubs also specify
   the local storage size of the data, in units of wchar_t.

   When called from a client stub, the wchar_t_net_size routine
   determines the value of conversion_type from conversion method and
   tag information set up in the binding handle by a code sets
   evaluation routine or a tag-setting routine.  Since wchar_t and
   idl_byte are completely different data types, the routine always
   sets the value to idl_cs_new_buffer_convert.  The routine sets the
   conversion_type parameter to this value and, if a conformant or
   conformant varying array is to be marshalled, calculates a new
   buffer size by multiplying the value of local_buffer_size by the
   byte size for wchar_t.  The routine returns the new buffer size in
   the network_buffer_size parameter. The size is specified in units
   of idl_byte, which is the network representation used for
   international character data.

   In cases where the binding handle does not contain the results of
   character and code sets evaluation, or where it is being called from
   the server stub, the wchar_t_net_size routine determines the value of
   conversion_type itself using the local code set value and the code set
   value passed in the network_code_set_value parameter, and returns the
   appropriate conversion_type value.  If a conformant or conformant
   varying array is to be marshalled, and the routine finds that a new
   buffer is required to hold the converted data, the routine calculates
   the size of this new buffer (by multiplying the value of
   local_buffer_size by sizeof(wchar_t); that is, the number of bytes
   required to encode one wchar_t data type, returns the results, in
   units of idl_byte, in network_buffer_size.

   Permissions Required

   No permissions are required.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: byte_local_size
              byte_net_size
              wchar_t_local_size