NAME

   idl_es_decode_incremental - Returns an incremental decoding handle
                               to the IDL encoding services

   Used by client and server applications.

 SYNOPSIS

   void idl_es_decode_incremental( idl_void_p_t state,
                                   idl_es_read_fn_t read_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 successive calls to the read_fn
        routine.  The state data structure acts as a communications
        channel between the application and the read_fn routine.

   Input

   read_fn
        Specifies the address of a user-provided routine that generates
        a buffer of encoded data for decoding by the IDL encoding
        services. The IDL encoding services call the read_fn routine
        repeatedly until all of the data has been decoded.

        The following C definition for idl_es_read_fn_t illustrates the
        prototype for the read_fn routine:

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

        The idl_es_decode_incremental() routine passes the specified
        state parameter value as input to the read_fn routine.  The
        state data structure is the communications path between the
        application and the read_fn routine. For example, the
        application can use the state parameter to pass in an open
        file pointer from which the read_fn routine is to read encoded
        data.

        The buffer parameter specifies the address of the data to be
        decoded; this address must be 8-byte aligned. The size parameter
        specifies the size of the buffer to be decoded, and must be a
        multiple of 8 bytes unless it represents the size of the last
        buffer to be decoded.  The read_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 decoding 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 code and its meaning is 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_decode_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_decode_incremental() routine returns an incremental
   decoding handle, which directs the IDL encoding services to decode
   data by calling the user-supplied read_fn routine, which generates
   a small buffer of encoded data for the IDL encoding services to
   decode. The routine passes the buffer address and size to the IDL
   encoding services, which then decode the buffer. The IDL encoding
   services call the read_fn routine repeatedly until there is no more
   data to decode.

 RETURN VALUES

   None.

 RELATED INFORMATION

   Functions: idl_es_encode_incremental
              idl_es_decode_buffer