dmParamsFlatten(3dm)

NAME
     dmParamsFlatten, dmParamsUnflatten - convert digital media parameter
     lists to and from byte strings

SYNOPSIS
     #include <dmedia/dm_params.h>

     size_t dmParamsFlatten
           ( const DMparams* sourceParams,
             const char* paramName,
             size_t bufferSize,
             void* buffer )

     DMstatus dmParamsUnflatten
           ( size_t bufferSize,
             const void* buffer, )
             DMparams* destinationParams )


DESCRIPTION
     These functions are used to convert a digital media parameter list into a
     form that can be written to a file or sent over a network, and then later
     to reconstruct the parameter list.

     dmParamsFlatten converts the parameters in sourceParams to a byte string
     and stores the result in the buffer provided by the caller.  There are
     two ways to use it: to store just one parameter, or to store the entire
     contents of a parameter list.

     To store just one parameter, pass the name of the desired parameter in
     paramName.  Its name, type, and value will be stored in the given buffer.
     If the named parameter is not present in sourceParams then a marker is
     written into the buffer indicating that it contains no data.

     To store everything in a parameter list, pass in NULL as the paramName.

     The bufferSize given indicates the number of bytes that dmParamsFlatten
     is allowed to write in buffer.  If the size given is insufficient to
     store the data, the buffer will be filled up to the allowed point, and
     then the rest of the bytes will be discarded.

     dmParamsFlatten returns the number of bytes needed to store the requested
     data, regardless of the bufferSize passed in.  To find out how much space
     will be required, call it with bufferSize=0 and buffer=NULL.

     dmParamsUnflatten converts a byte string back into a parameter list.
     Each of the parameter name/type/value triples stored in the byte string
     is copied into destinationParams.  It is OK for destinationParams to
     already contain data; if there are any name conflicts, the values in the
     byte string will replace the pre-existing values.
     dmParamsUnflatten will return DM_SUCCESS or DM_FAILURE.  It can fail if
     the byte string provided to it is not valid or if there is not sufficient
     memory hold the parameters being restored.  It may not detect failure
     until some of the parameters have been restored, in which case
     destinationParams will have some, but not all, of its parameters
     modified.

EXAMPLE
           DMparams* original;
           DMparams* restored;
           char buffer[1000];
           size_t size;

           original = myCreateParams();  /* any parameter list */

           size = dmParamsFlatten( original, NULL, 1000, buffer );

           if ( size > 1000 ) {
              printf( "%d bytes required\n",
                      dmParamsFlatten( original, NULL, 0, NULL ) );
              exit( 1 );
           }

           if ( dmParamsCreate( &restored ) != DM_SUCCESS ) {
              printf( "Out of memory.\n" );
              exit( 1 );
           }
           if ( dmParamsUnflatten( size, buffer, restored )
                != DM_SUCCESS ) {
              printf( "Restoration failed.\n" );
              exit( 1 );
           }

           /* both "original" and "restored" now contain the */
           /* same data. */

           dmParamsDestroy( original );
           dmParamsDestroy( restored );



SEE ALSO
     dmParams(3dm).