Next: , Previous: Header Field Manipulations, Up: Header Field Manipulations   [Contents]


A.2.1 bpipe_hdrf_add

Add a new data field to the header.

Synopsis

#include <bpipe/bpipe.h>

int bpipe_hdrf_add(
  BPipe *bpipe,
  const char *name,
  BPDataType type,
  BPMatrix *matrix,
  void *data,
  int copy
);

Parameters

BPipe *bpipe

binary pipe to which to add the field

const 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

BPMatrix *matrix

the matrix specification

void *data

a pointer to the field’s data

int copy

if true, make a copy of the data

Description

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.

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
BPEBADPIPE
BPENOMEM

a memory allocation failed


Next: , Previous: Header Field Manipulations, Up: Header Field Manipulations   [Contents]