All Fluke IPC calls that cause data to be transferred take as a parameter a pointer to a parameter structure of type fluke_ipc_params_t. The exact definition and layout of this structure is processor architecture-specific; however, the structure is guaranteed to have at least the following fields:
fluke_ipc_buf_t send_buf; /* first data buffer to send */ fluke_ipc_buf_t *send_buf_tab; /* additional data buffers to send */ fluke_ipc_buf_count_t send_buf_count; /* number of additional buffers */ fluke_ref_t **send_ref_tab; /* references to send */ fluke_ipc_ref_count_t send_ref_count; /* number of references to send */ fluke_ipc_buf_t recv_buf; /* first data buffer to receive into */ fluke_ipc_buf_t *recv_buf_tab; /* additional data buffers to receive */ fluke_ipc_buf_count_t recv_buf_count; /* number of additional buffers */ fluke_ref_t **recv_ref_tab; /* references to receive into */ fluke_ipc_ref_count_t recv_ref_count; /* number of references to receive */}
The send_* fields in the parameters structure describe data and references to send in a sending operation; these fields are ignored by operations that only receive. Similarly, the recv_* fields describe data buffers and references into which to receive incoming messages; these fields are ignored by operations that only send.
Specific data buffers to send from or receive into are specified using structures of type fluke_ipc_buf_t, which contains at least the following fields:
natural_t words; /* size of buffer in IPC words */ void *buf; /* pointer to beginning of buffer */}
The words field specifies the length of the data buffer in IPC words (fluke_ipc_word_t), and the buf field contains a pointer to the actual data buffer. There may be architecture-specific alignment constraints on the data buffer.
The send_buf field describes the first buffer of simple data to send. In sending operations that logically begin a message (fluke_ipc_call, fluke_ipc_send or reliable operations involving connect_send or ack_send), this first simple data buffer must always be present, and send_buf.words must be at least FLUKE_MIN_MSG_WORDS. In sending operations that don't begin a message (i.e. a ``plain'' send), the word count can be any nonnegative number, including zero.
The send_buf_tab field is meaningful only if send_buf_count is nonzero, and points to an array of fluke_ipc_buf structures describing additional simple data buffers to be sent. The send_buf_count is the number of entries in this array. The word count in any of these buffer descriptions can be zero; in that case, that buffer entry is skipped and causes no data to be sent.
The send_ref_tab field points to an array of pointers to Fluke reference objects containing references to be passed. The number of references to be sent in this way is indicated by send_ref_count. If send_ref_count is nonzero, then all of the reference pointers in the array must be valid and point to active reference objects; null pointers are not allowed in this array. (However, pointers to null references may be present in the array, in which case the null reference is passed to the receiver.)
The send parameter fields in the fluke_ipc_params structure are not modified during any Fluke IPC operation.
The receive-related fields work exactly the same way as the send fields, except they are used for receive operations instead of send operations. However, unlike send operations which always send all of the data and references specified unless the IPC connection is abnormally broken for some reason, receive operations only fill the receive buffers and references with as much data and references as the sender sent. Thus, when a receive operation completes, the Fluke implementation must indicate to the application how many data words and references were actually received. It does this by adjusting the recv_buf.words, recv_buf_count, and recv_ref_count fields of the IPC parameter structure before returning.
On return from a receiving IPC operation, the recv_buf_count is decreased by the number of data buffers that were completely filled with receive data, starting with the first buffer (the buffer specified by the caller in recv_buf). The recv_buf.words field indicates the number of data words remaining in the first receive buffer that was not completely filled. If all data buffers were completely filled and the sender still had more data, the receive call will return with FLUKE_IPC_RECV_MORE_DATA indicating that another receive call should be made. The recv_ref_count, on return from the IPC operation, is decreased by the number of references that were received; it indicates the number of unreceived references remaining in the recv_ref_tab provided. If all references in the table were used and the sender still had more to send, the receive call will return with FLUKE_IPC_RECV_MORE_REFS indicating that another receive call should be made.
On return from a receiving IPC operation, all of the receive parameter fields other than the ones describe above may have been modified, and are left with undefined contents. However, no receive parameter fields will be modified (or used at all) in IPC operations that don't involve receiving anything. Furthermore, although the contents of the parameter structure may be modified, any receive buffer table or receive reference pointer table provided (pointed to by recv_buf_tab and recv_ref_tab, respectively) will not be modified by the IPC operation, although of course the buffers and references they refer to will be modified.