Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Frame Sets


Typedefs

typedef _cpl_frameset_ cpl_frameset
 The frame set data type. More...


Functions

cpl_frameset * cpl_frameset_new (void)
 Create a new, empty frame set. More...

cpl_frameset * cpl_frameset_copy (const cpl_frameset *set)
 Create a copy of the given frame set. More...

void cpl_frameset_delete (cpl_frameset *set)
 Destroy a frame set. More...

long cpl_frameset_get_size (const cpl_frameset *set)
 Get the current size of a frame set. More...

long cpl_frameset_max_size (const cpl_frameset *set)
 Get the maximum number of frame set entries possible. More...

int cpl_frameset_is_empty (const cpl_frameset *set)
 Check whether a frame set is empty. More...

long cpl_frameset_count (const cpl_frameset *set, const char *tag)
 Counts the frames stored in a frame set having the given tag. More...

cpl_framecpl_frameset_find (const cpl_frameset *set, const char *tag)
 Find a frame with the given tag in a frame set. More...

cpl_framecpl_frameset_begin (const cpl_frameset *set)
 Get the first frame in the given set. More...

cpl_framecpl_frameset_next (const cpl_frameset *set)
 Get the next frame in the given set. More...

int cpl_frameset_insert (cpl_frameset *set, cpl_frame *frame)
 Insert a frame into the given frame set. More...

int cpl_frameset_erase (cpl_frameset *set, const char *tag)
 Erase all frames with the given tag from a frame set. More...

int cpl_frameset_erase_frame (cpl_frameset *set, cpl_frame *frame)
 Erase the given frame from a frame set. More...

cpl_frameset * cpl_frameset_load (const char *name, cpl_frameset *set)
 Create a new frame set from a set of frames file. More...

int cpl_frameset_save (const cpl_frameset *set, const char *name)
 Write a frame set to a set of frames file. More...


Detailed Description

The module implements a container type for frames. Frames can be stored in a frame set and retrieved, either by searching for a particular frame tag or by sequential access. Frame sets can be created, filled and saved to a so called `set of frames' file or loaded from such a file.
Synopsis:
   #include <cpl_frameset.h>

Typedef Documentation

typedef struct _cpl_frameset_ cpl_frameset
 

The frame set data type.

This data type is opaque.


Function Documentation

cpl_frame* cpl_frameset_begin const cpl_frameset   set
 

Get the first frame in the given set.

Parameters:
set  A frame set.
Returns:
Handle for the first frame in the set, or NULL if the set is empty.
The function returns the first frame in the frame set set if it exists. If a first frame does not exist, i.e. the frame set is empty, NULL is returned. The function also updates the internal cache.

See also:
cpl_frameset_next()

cpl_frameset* cpl_frameset_copy const cpl_frameset   set
 

Create a copy of the given frame set.

Parameters:
set  The frame set to be copied.
Returns:
The created copy.
The function creates a deep copy, i.e. the frame set object and its contents, of the frame set set. The created copy and the original set do not share any resources.

long cpl_frameset_count const cpl_frameset   set,
const char *    tag
 

Counts the frames stored in a frame set having the given tag.

Parameters:
set  A frame set.
tag  The frame tag.
Returns:
The number of frames with tag tag.
The function scans the frame set set for frames with the tag tag and returns the number of frames found.

void cpl_frameset_delete cpl_frameset   set
 

Destroy a frame set.

Parameters:
set  The frame set to destroy.
Returns:
Nothing.
The function destroys the frame set set and its whole contents.

int cpl_frameset_erase cpl_frameset   set,
const char *    tag
 

Erase all frames with the given tag from a frame set.

Parameters:
set  A frame set.
tag  The tag used to locate the frames to remove.
Returns:
The function returns the number of frames removed.
The function searches the frame set set for frames having the tag tag and removes them from the set. The removed frames are destroyed. If no frame with the tag tag is found the function has no effect.

int cpl_frameset_erase_frame cpl_frameset   set,
cpl_frame   frame
 

Erase the given frame from a frame set.

Parameters:
set  A frame set.
frame  The frame to remove.
Returns:
The function returns 0 on success, or 1 otherwise.
The function searches the frame set set for the first occurrance of frame. If it is present, the frame is removed from the set and destroyed. If frame is not present in set the function has no effect.

cpl_frame* cpl_frameset_find const cpl_frameset   set,
const char *    tag
 

Find a frame with the given tag in a frame set.

Parameters:
set  A frame set.
tag  The frame tag to search for.
Returns:
The handle for a frame with tag tag, or NULL if no such frame was found.
The function searches the frame set set for the frames with the tag tag. If such a frame is present, a handle for it is returned. If the set contains several frames with the tag tag the first one is returned. The remaining frames with this tag can be accessed sequentially by using NULL as tag when calling this function repeatedly, since the most recent frame accessed is cached. This cache is reset whenever the provided tag is not NULL. If no frame with the tag tag is present in set or no more frames with this tag are found the function returns NULL.

long cpl_frameset_get_size const cpl_frameset   set
 

Get the current size of a frame set.

Parameters:
set  A frame set.
Returns:
The frame set's current size, or 0 if it is empty.
The reports the current number of frames stored in the frame set set.

int cpl_frameset_insert cpl_frameset   set,
cpl_frame   frame
 

Insert a frame into the given frame set.

Parameters:
set  A frame set.
frame  The frame to insert.
Returns:
The function returns 0 on success, or 1 otherwise.
The function adds the frame frame to the frame set set using the frame's tag as key.

int cpl_frameset_is_empty const cpl_frameset   set
 

Check whether a frame set is empty.

Parameters:
set  A frame set.
Returns:
The function returns 1 if the set is empty, and 0 otherwise.
The function checks if set contains any frames.

cpl_frameset* cpl_frameset_load const char *    name,
cpl_frameset   set
 

Create a new frame set from a set of frames file.

Parameters:
name  Input file path.
set  Frame set to be updated with the contents of name.
Returns:
Pointer to the newly created frame set if set was NULL, or the updated set set. In case an error occurred the return value is NULL.
The function reads the given input file filename and either, if NULL is passed for set, creates a new frame set from its contents, or updates set, if set points to an already existing frame set.

Note:
The current format of the set of frames file is as follows:
  • One frame description per line.
  • Each frame description consists of an absolute file path followed by the frame tag and, optionally, the group the frame belongs to.
  • Currently the only defined group tags are RAW, CALIB and PRODUCT.
  • The individual fields are separated by whitespace.

long cpl_frameset_max_size const cpl_frameset   set
 

Get the maximum number of frame set entries possible.

Parameters:
set  A frame set.
Returns:
The maximum number of frames that can be stored in the list.
The function reports the capacity of the frame set set, i.e. the maximum number of frames which can be stored in the list.

cpl_frameset* cpl_frameset_new void   
 

Create a new, empty frame set.

Returns:
A handle for the newly created frame set.
The function allocates the memory for the new frame set, initialises the set to be empty and returns a handle for it.

cpl_frame* cpl_frameset_next const cpl_frameset   set
 

Get the next frame in the given set.

Parameters:
set  A frame set.
Returns:
Handle for the next frame in a set. If there are no more frames in the set the function returns NULL.
The function returns the next frame in the frame set set if it exists and otherwise NULL. The function uses the internal cache to determine the most recently accessed frame. This means that the function only works as expected if set has been initialised by a call to cpl_frameset_begin(), and if no function updating the internal cache was called between two subsequent calls to this function.

See also:
cpl_frameset_first()

int cpl_frameset_save const cpl_frameset   set,
const char *    name
 

Write a frame set to a set of frames file.

Parameters:
set  Frame set to be saved.
name  Output file path.
Returns:
The function returns 0 if the frame set was successfully written, or 1 otherwise.
The function writes the filename, frame and the frame group to the set of frames file name for each frame in the set set that has a filename. Frames having no filename set are silently ignored. If a frame has no frame tag the string "UNKNOWN" will be written instead. If no frame group is given for a particular frame the frame group is omitted.

Note:
This function is mainly provided for debugging purposes.


Generated on Mon May 24 14:58:06 2004 for Common Pipeline Library Reference Manual by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002