Next: , Up: CMS

4.1 CMS Basics

All operations with the CMS framework require the use of a so called CMS object which is internally used to keep track of the current state and to store some meta information.

— Data type: ksba_cms_t

The ksba_cms_t type is used for this CMS object.

— Data type: ksba_stop_reason_t

The ksba_stop_reason_t type is an enumeration used for communication between the phases of a parsing or building process.

— Function: ksba_cms_t ksba_cms_new (void)

This function creates a new CMS object. The only reason the function may fail is an out-of-memory condition in which case NULL is returned. It is safe for the caller to translate this to the standard error code GPG_ERR_ENOMEM. Any object created with this function should be released after use by using ksba_cms_release.

— Function: void ksba_cms_release (ksba_cms_t cms)

Release all resources associated with the CMS object. It is perfectly okay to pass NULL to this function in which case nothing happens.

— Function: gpg_error_t ksba_cms_set_reader_writer (ksba_cms_t cms, ksba_reader_t r, ksba_writer_t w)

About all usages of the CMS framework require some input and output data (great surprise!). To accomplish this in the most abstract way, no direct output functions are used - instead special reader and writer objects are used instead. Depending on the desired operations either a reader, a writer or both must be given. Associate a reader object with cms by passing it as r and a writer object by passing it as w. Note that no reference counting is done,so make sure that those objects have a lifetime at least as long as CMS.

If you forget to set these objects, you will get an appropriate error later when data is actually to be read or written. The function returns zero on success or an error code when invalid objects are passed.