idl_es_decode_incremental(3rpc)
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 (*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.
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.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_no_memory
Insufficient memory available to complete operation.
Related Information
Functions: idl_es_encode_incremental(3rpc)