idl_es_encode_incremental(3rpc)

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 successive calls to 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.

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.

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_decode_incremental(3rpc)

idl_es_encode_fixed_buffer(3rpc)

idl_es_encode_dyn_buffer(3rpc)