Next: , Previous: bpipe_hdrf_add, Up: Header Field Manipulations


A.2.2 bpipe_hdrf_array_add

Add a one-dimensional array field to the header.

Synopsis

     #include <bpipe/bpipe.h>
     
     
     
int bpipe_hdrf_array_add( BPipe *bpipe, char *name, BPDataType type, void *data, size_t extent, int copy );

Parameters

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 a BPDataType 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
void *data
a pointer to the field's data
size_t extent
the extent of the array
int copy
if true, make a copy of the data

Description

This routine adds a one dimesional array 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 specification is duplicated.

This routine simplifies the addition of one-dimensional arrays. Normally one must construct a matrix specification and call bpipe_hdrf_add. This routine takes care of that.

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.

Returns

It returns zero upon success. Upon failure it returns non-zero, and sets bpipe_errno.

Errors

Upon error bpipe_errno is set to one of the following:

BPEBADARG

BPENOMEM
a memory allocation failed