udi_buf_copy(3udi)

---

Copy data from one logical buffer to another

SYNOPSIS

#include <udi.h>

void udi_buf_copy (

	udi_buf_copy_call_t *callback,

	udi_cb_t *gcb,

	udi_buf_t *src_buf,

	udi_size_t src_off,

	udi_size_t src_len,

	udi_buf_t *dst_buf, 

	udi_size_t dst_off,

	udi_size_t dst_len,

	udi_buf_path_t path_handle );
 
typedef void udi_buf_copy_call_t (

	udi_cb_t *gcb, 

	udi_buf_t *new_dst_buf );
 

ARGUMENTS callback, gcb are the standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions"

src_buf is a pointer to the buffer containing data to be copied. This must not be set to NULL.

src_off is the offset, in bytes, from the first logical data byte to the start of the copy area in the source buffer. This must not exceed the current size of the buffer:

0 £ src_off < src_buf->buf_size

src_len is the number of bytes to be copied from the source buffer. src_len must be at least 1, and src_off + src_len must not extend beyond the current buffer size:

0 < src_len £ (src_buf->buf_size - src_off)

For src_len of zero, use udi_buf_write instead.

dst_buf is a pointer to the buffer that is the target of the data copy. If set to NULL, a new, empty buffer will be allocated before copying the source data.

dst_off is the offset, in bytes, from the first logical data byte to the start of the copy area in the destination buffer. The buffer will be extended if necessary to accommodate the data.

0 £ dst_off £ dst_buf->buf_size

dst_len is the number of bytes in dst_buf to be replaced with data copied from the source buffer.

0 £ dst_len £ (dst_buf->buf_size - dst_off)

If dst_buf is NULL, both dst_off and dst_len must be zero.

path_handle is the handle identifying the intended use and dispatching if a new buffer must be allocated for this request. Path handle usage is determined by the driver, but by associating the use of a specific path_handle with buffers allocated for a specific purpose, the driver allows the environment to predict and optimize the allocated buffer requirements. If dst_buf is not NULL on entry, its existing path will continue to be used and this parameter must be set to UDI_NULL_BUF_PATH; otherwise it must be non-null.

new_dst_buf is a pointer to the new, modified destination buffer.

DESCRIPTION udi_buf_copy logically replaces dst_len bytes of data starting at offset dst_offset in dst_buf with a copy of src_len bytes of data starting at src_offset in src_buf. When the data has been copied, the callback routine is called.

Table 13-1 Common actions for udi_buf_copy/udi_buf_write arguments

Action	src_buf/src_mem	src_len	dst_buf	dst_len
Allocate/initialize	non-null	N	NULL	0
Overwrite	non-null	N	non-null	N
Delete	NULL/NULL	0	non-null	N
Insert	non-null	N	non-null	0
Ensure space	NULL/NULL	N	NULL	0

If dst_len is zero, the src_len bytes of source data will be inserted in the destination buffer at dst_off. If dst_len is positive, the dst_len bytes will be replaced by src_len bytes from the source buffer. The src_len parameter must be > 0 bytes. (For a src_len of zero, udi_buf_write must be used.)

This routine is very similar to udi_buf_write, except that the data source is another buffer, rather than a virtually-contiguous data structure.

If dst_buf is NULL, a new buffer will be allocated to hold the data.

The destination buffer will be extended or reallocated as necessary to hold any new data being added to the buffer. This extension or reallocation is performed by the environment as part of the udi_buf_copy operation and all data in the destination buffer not described by the dst_off and dst_len region will be preserved. This reallocation may result in a new buffer being returned in the callback, therefore the dst_buf should no longer be used after passing it to udi_buf_copy and the driver must use the new_dst_buf value following the callback.

It is expected that this routine will efficiently duplicate buffers (e.g., when multiple higher levels above a multiplex point must receive the same inbound buffer). Because UDI implementations may avoid copying data whenever possible, the actual allocation of space for the copied data may be delayed until the shared data is written via either buffer.

WARNINGS Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".

src_buf and dst_buf must not reference the same buffer.

On successful completion, dst_buf will no longer be valid and new_dst_buf is substituted, even if dst_buf was not specified as NULL. new_dst_buf may be set to the same handle value as the input value of dst_buf, but the driver must not depend on this.

If this operation is cancelled with udi_cancel, any pre-existing dst_buf buffer will be discarded (see udi_cancel for an explanation of why this is so).

REFERENCES udi_buf_write, udi_cancel