NAME

   idl_es_encode_incremental - Returns an incremental encoding handle
                               to the IDL encoding services

   Used by client and server applications.

 SYNOPSIS

   void idl_es_encode_incremental( idl_void_p_t state,
                                   idl_es_allocate_fn_t allocate_fn,
                                   idl_es_write_fn_t write_fn,
                                   idl_es_handle_t *es_handle,
                                   error_status_t *status );

 PARAMETERS

   Input/Output

   state
        Specifies the address of an application-provided data structure
        that coordinates the actions of the allocate_fn and write_fn
        routines.  The state data structure acts as a communications
        channel between the application and the allocate_fn and
        write_fn routines.

   Input

   allocate_fn
        Specifies the address of a user-provided routine that allocates
        an empty buffer.  The encoding stub uses the allocated buffer to
        store encoded data.

        The following C definition for idl_es_allocate_fn_t illustrates
        the prototype for the buffer allocation routine:

             typedef void (*idl_es_allocate_fn_t)
              (
               idl_void_p_t    state,            /* in/out */
               idl_byte        **buffer,         /* out */
               idl_ulong_int   *size,            /* in/out */
              );

        The idl_es_encode_incremental() routine passes the specified
        state parameter value as input to the allocate_fn buffer
        allocation routine.  When the IDL encoding services call the
        allocate_fn routine, the value at the address indicated by
        size represents the buffer size that the IDL encoding services
        have requested the routine to allocate.  When the allocate_fn
        buffer allocation routine allocates the buffer, it writes the
        actual size of the allocated buffer to this parameter; the value
        must be a multiple of eight bytes.  The buffer parameter
        specifies the address of the allocated buffer; this address must
        be 8-byte aligned.  The allocate_fn routine should return an
        exception on error.

   write_fn
        Specifies the address of a user-provided routine that writes the
        contents of a buffer that contains data that has been encoded by
        the IDL encoding services. The IDL encoding services will call
        this routine when the buffer allocated by allocate_fn is full,
        or when all of the application's encoding operation parameters
        have been encoded.

        The following C definition for idl_es_write_fn_t illustrates the
        prototype for the write_fn routine:

             typedef void (*idl_es_write_fn_t)
              (
               idl_void_p_t    state,            /* in/out */
               idl_byte        *buffer,          /* in */
               idl_ulong_int   size,             /* in */
              );

        The idl_es_encode_incremental() routine passes the specified
        state parameter value as input to the write_fn routine.  The
        buffer parameter value is the address of the data that the
        IDL encoding services have encoded. The size parameter value
        is the size, in bytes, of the encoded data.

        The write_fn routine should return an exception on error.

   Output

   es_handle
        Returns the address of an IDL encoding services handle for use
        by a client or server encoding operation.

   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_no_memory
                       Insufficient memory available to complete
                       operation.

 DESCRIPTION

   The IDL encoding services provide client and server RPC applications
   with a method for encoding data types in input parameters into a byte
   stream and decoding data types in output parameters from a byte
   stream without invoking the RPC runtime. Encoding and decoding
   operations are analogous to marshalling and unmarshalling, except that
   the data is stored locally, and is not transmitted over the network.
   Client and server applications can use the IDL encoding services to
   create persistent storage for their data.  Encoding "flattens"
   complex data types into a byte stream for storage on disk, while
   decoding restores the flattened data to complex form.

   The idl_es_encode_incremental() routine belongs to a set of routines
   that return handles to the IDL encoding services for use by client
   and server encoding and decoding operations. The information in the
   handle controls the way in which the IDL encoding services manage
   memory when encoding or decoding data.

   The idl_es_encode_incremental() routine returns an incremental
   encoding handle, which directs the IDL encoding services to encode
   data into a chain of small buffers that the user-provided
   allocate_fn routine manages.  The user-provided write_fn routine
   writes the encoded data in these buffers back for access by the
   application.

   The state data structure is the communications path between the
   application and the allocate_fn and write_fn routines.  For example,
   the application can build a cache of pre-allocated memory to store
   encoded data, and store pointers to that pre-allocated memory in the
   state data structure.  When invoked by the IDL encoding services to
   allocate a buffer, the allocate_fn routine can search the state data
   structure for a free memory location to use.

 RETURN VALUES

   None.

 RELATED INFORMATION

   Functions: idl_es_decode_incremental
              idl_es_encode_fixed_buffer
              idl_es_encode_dyn_buffer