dmParamsFlatten(3dm)					  dmParamsFlatten(3dm)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #include <dmedia/dm_params.h>

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

     DMstatus dmParamsUnflatten    [Toc]    [Back]
	   ( size_t bufferSize,
	     const void* buffer, )
	     DMparams* destinationParams )

DESCRIPTION    [Toc]    [Back]

     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.





									Page 1






dmParamsFlatten(3dm)					  dmParamsFlatten(3dm)



     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    [Toc]    [Back]

	   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    [Toc]    [Back]

     dmParams(3dm).


									PPPPaaaaggggeeee 2222