Auxiliary data

---

Detailed Description

Auxiliary data can be stored both in the header and along with each image.

Auxiliary header

The auxiliary header contains a description of the auxiliary data (format) attached to each image. Interpretation is left to the application. It is also possible to only store information in the header, without adding to the image size (maximum data length = 0). This way, the description field in the header contains all relevant information.

Auxiliary data

Each image can contain a variable amount of auxiliary data (up to the maximum size specified in the header).

For standard I/O: the auxiliary data shall be accessed in the same order as the data is stored in the file. This corresponds with the order in the header. Note that auxiliary data must be accessed before any image components. Furthermore, for interlaced files only field access can be used. For file I/O these restriction do not apply.

Functions
int	p_mod_add_aux (pT_header *header, int max_size, const char *name, int descr_len, const char *description)
int	p_get_num_aux (const pT_header *header)
int	p_get_aux_by_name (const pT_header *header, const char *name)
pT_status	p_mod_rm_aux (pT_header *header, int aux_id)
pT_status	p_get_aux (const pT_header *header, int aux_id, int *max_size, char *name, int *descr_len, char *description)
pT_status	p_read_aux (const char *filename, pT_header *header, int frame, int field, int aux_id, int *size, unsigned char *buf)
pT_status	p_write_aux (const char *filename, pT_header *header, int frame, int field, int aux_id, int size, unsigned char *buf)

---

Function Documentation

int p_mod_add_aux (  pT_header *  header, int  max_size, const char *  name, int  descr_len, const char *  description )

Add an auxiliary header to header structure Parameters: header  The pfspd header to modify max_size  Maximum data length per image (0: only information in header) name  Name of auxiliary data descr_len  Number of bytes in description description  descr_len bytes, to be placed in the auxiliary header Returns: -1: error, >= 0: auxiliary ID NB: -1 can be returned in two ways: 'name' already exists not enough space in aux. header to allocate this request

int p_get_num_aux (  const pT_header *  header  )

Get number of auxiliary header IDs

int p_get_aux_by_name (  const pT_header *  header, const char *  name )

Get ID of an auxiliary header by name

pT_status p_mod_rm_aux (  pT_header *  header, int  aux_id )

Remove auxiliary header from header structure Parameters: header  The header to modify aux_id  ID of the auxiliary data Returns: P_OK, P_INVALID_AUXILIARY

pT_status p_get_aux (  const pT_header *  header, int  aux_id, int *  max_size, char *  name, int *  descr_len, char *  description )

Get all properties of an auxiliary header Parameters: header  The header to read aux_id  Auxiliary ID max_size  Maximum data length per image. May be NULL. name  Name of auxiliary data. May be NULL. Must be allocated by the caller, size P_SAUX_NAME+1. descr_len  Number of bytes in description. May be NULL. description  Data description. May be NULL. Must be allocated by the caller, size given by descr_len. Returns: P_OK, P_INVALID_AUXILIARY

pT_status p_read_aux (  const char *  filename, pT_header *  header, int  frame, int  field, int  aux_id, int *  size, unsigned char *  buf )

Read auxiliary data of one image Parameters: filename  Filename ('-' = stdio) header  header structure frame  Frame number field  0: frame, 1/2: field access aux_id  Auxiliary ID size  Actual data length buf  Buffer for auxiliary data. Must be allocated by the caller, maximum size given by the max_size parameter of p_get_aux().

pT_status p_write_aux (  const char *  filename, pT_header *  header, int  frame, int  field, int  aux_id, int  size, unsigned char *  buf )

Write auxiliary data of one image Parameters: filename  Filename ('-' = stdio) header  header structure frame  Frame number field  0: frame, 1/2: field access aux_id  Auxiliary ID size  Actual data length. Maximum length is given by the max_size parameter of p_get_aux(). buf  Buffer for auxiliary data Returns: P_OK, P_INVALID_AUXILIARY, P_EXCEEDING_AUXILIARY_SIZE

---