Next: bpipe_hdrf_array_add, Previous: Header Field Manipulations, Up: Header Field Manipulations
Add a new data field to the header.
#include <bpipe/bpipe.h>int bpipe_hdrf_add( BPipe *bpipe, char *name, BPDataType type, BPMatrix *matrix, void *data, int copy );
BPipe *bpipe
- binary pipe to which to add the field
char *name
- the name of the field
BPDataType type
- the field's datatype
Possible values for aBPDataType
are as follows:BPDType_char
,BPDType_double
,BPDType_int
,BPDType_uint
,BPDType_DVector2
,BPDType_DVector3
,BPDType_IVector2
,BPDType_IVector3
,BPDType_UIVector2
,BPDType_UIVector3
,BPDType_DComplex
,BPDType_DCVector2
,BPDType_DCVector3
BPMatrix *matrix
- the matrix specification
void *data
- a pointer to the field's data
int copy
- if true, make a copy of the data
This routine adds a data field to the header associated with the
passed BPipe
. Duplicate fields with the same name are
allowed; they are given different index numbers. The new field
is added to the end of the list of existing fields.
The passed name is duplicated. If the matrix specification is
NULL
, a matrix specification for a scalar is constructed. If
the copy
argument is true, a copy is made of the data pointed
to by the data
argument. Otherwise, the header field will
refer directly to the memory it points to. This saves time and
space for large data fields. if the passed data pointer is
NULL
, memory is allocated for it, regardless of the state of
the copy
flag.
If the calling procedure constructs a matrix specification (a
BPMatrix
structure), bpipe_hdrf_add
uses
this structure as is and directs the BPipe
cleanup code to take
responsibility for freeing it. The calling procedure should
not free it, nor should it pass it to any other BPipe
routine which takes responsibility for freeing it. It should not
alter it in any way after passing it to bpipe_hdrf_add
.
It returns zero upon success. Upon failure it returns non-zero,
and sets bpipe_errno
.
Upon error bpipe_errno
is set to one of the following:
BPEBADARG
BPEBADPIPE
BPipe
has been mapped
BPENOMEM