NAME

   cs_byte_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/codesets_stub.h>

   void cs_byte_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 information 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 idl_byte, 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 existing storage is sufficient for storing the results of
       the conversion. The conversion type can be one of the following
       values:

       idl_cs_no_convert
                      No code set conversion is required.

       idl_cs_in_place_convert
                      Code set conversion can be performed in the
                      current buffer.

       idl_cs_new_buffer_convert
                      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 cs_byte_net_size() routine
   raises an exception to the client application.

 DESCRIPTION

   The cs_byte_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 cs_byte_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 new one is
   required). 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 cs_byte_*_size routines when the
   cs_byte type (which is equivalent to byte) has been specified as
   the local data type using the cs_char attribute in the attribute
   configuration file for the application.  Applications do not call
   the cs_byte_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 byte.

   When called from a client stub, the cs_byte_net_size() routine
   determines the value of conversion_type from the client and server's
   code set tag information set up the binding handle by a code sets
   evaluation routine or a tag-setting routine. If the conversion type
   specified in the handle is 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 c_max_bytes value for the code set
   specified in network_code_set_value (the sending tag parameter).

   The routine returns the new buffer size in the network_buffer_size
   parameter. The size is specified in units of cs_byte, which is the
   network representation used for international character data (and
   is equivalent to the byte type). For fixed and varying arrays, the
   routine assumes that local_buffer_size is sufficient to store the
   converted data.

   If the handle information specifies idl_cs_convert_in_place or
   idl_cs_no_convert, the routine assumes that local_buffer_size can
   store the converted data (or that no conversion is necessary) and
   returns idl_cs_convert_in_place (or idl_cs_no_convert) in the
   conversion_type parameter. The routine also returns the value of
   local_buffer_size in network_buffer_size if a conformant or
   conformant varying array is to be marshalled.

   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 cs_byte_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 the network code set c_max_bytes value) and
   returns the results, in units of cs_byte, in network_buffer_size.

   Permissions Required

   No permissions are required.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: cs_byte_local_size
              wchar_t_local_size
              wchar_t_net_size