Errors encountered while using the Digital Media Libraries can be diagnosed with the help of two routines. The function dmGetError() retrieves the number, summary, and detailed description of an error generated by the execution of the current process. The current process in this case is the same as determined by getpid(). The companion function, dmGetErrorForPID(), gets the same type of error information for a process your application specifies.

const char *dmGetError ( int *errornum,
                         char error_detail[DM_MAX_ERROR_DETAIL] )
const char *dmGetErrorForPID ( pid_t pid, int *errornum,
                               char error_detail[DM_MAX_ERROR_DETAIL] )

The functions dmGetError() and dmGetErrorForPID() enable your application to handle in a consistent manner errors generated while using the digital media libraries. Both functions return a pointer to a null-terminated character string that summarizes the error. The setting of the errors by the libraries and the retrieval of them by your application is guaranteed to be thread-safe. Only the most recent error for a given thread is returned. If there are no errors, the functions return NULL.

The parameter pid in dmGetErrorForPID() is the id of the process in which to check for an error. The last parameter in both functions, error_detail, is the address of a null-terminated character array of size DM_MAX_ERROR_DETAIL. If one exists, a detailed description of the error is loaded into the array. If you set error_detail to NULL, no description is loaded. The remaining parameter, errornum, is a pointer to an integer into which the number of the current error is loaded. If your application sets errornum to NULL, no number is loaded. The error numbers returned in errornum fall into ranges according to the digital media libraries that generated them. The currently defined error ranges and their libraries are as follows:

Some libraries require you to allocate memory for DMparams lists, but with the DM library, you need not allocate memory for DMparams lists, because memory management is provided for you by the dmParamsCreate() and dmParamsDestroy() routines. These routines work together as a self-contained block within which you create the DMparams list, set the parameter value(s) and use them, and then destroy the structure, freeing its associated memory.

Only the dmParamsCreate() function can create a DMparams list, and only the dmParamsDestroy() function can free one. This means that DMparams lists are managed correctly when every call to create one is balanced by a call to destroy one. The creation function can fail because of lack of memory, so it returns an error code. The destructor can never fail.

To create an empty DMparams list, call dmParamsCreate(). Its function prototype is:

DMstatus dmParamsCreate ( DMparams** returnNewList )

where:

If there is sufficient memory to allocate the structure, a pointer to the newly created structure is put into *returnNewList and DM_SUCCESS is returned; otherwise, DM_FAILURE is returned.

When you have finished using the DMparams list, you must destroy it to free the associated memory. To free both the DMparams list structure and its contents, call dmParamsDestroy(). Its function prototype is:

void dmParamsDestroy ( DMparams* params )

where:

Example 3-1 is a code fragment that creates a DMparams list called params, then calls a Movie Library routine, mvSetMovieDefaults(), to initialize the default movie parameters, and finally destroys the list, freeing both the structure and its contents.

DMparams* params;
if ( dmParamsCreate( &params ) != DM_SUCCESS ) {
    printf( "s\n", dmGetError(NULL, NULL) );
    exit( 1 );
}
if ( mvSetMovieDefaults(params, MV_FORMAT_SGI_3) != DM_SUCCESS ) {
    printf( “s\n”, mvGetErrorStr(mvGetErrno()));
    exit( 1 );
}
dmParamsDestroy ( params );

After creating an empty DMparams list or a default audio or image configuration, you can use the routines described in this section to set and get values for individual elements of a DMparams list.

There is a routine for setting and getting the parameter values for each parameter data type defined in the DM Library, as listed in Table 3-1.

All of these functions store and retrieve entries in a DMparams list. They assume that the named parameter is present and is of the specified type; the debugging version of the library asserts that this is the case. All functions that can possibly fail return an error code indicating success or failure. Insufficient memory is the only reason these routines can fail. Type mismatch causes a failed assertion in the debug library and undefined results in the non-debug library.

Table 3-2 lists the DM Library routines for setting parameter values. All the routines except dmParamsSetBinary() require three arguments:

These routines return either DM_SUCCESS or DM_FAILURE.

Table 3-3 lists the DM Library routines for getting parameter values. All the routines except dmParamsGetBinary() require two arguments:

Routines that get values return either a pointer to a value or the value itself. For strings, DMparams lists, and table-of-contents entries, the pointer that is returned points into the internal data structure of the DMparams list. This pointer should never be freed and is only guaranteed to remain valid until the next time the list is changed. In general, if you need to keep a string value around after getting it from a DMparams list, it should be copied.

This section explains how to manipulate DMparams lists. Some of the tasks you can two with DMparams lists include:

Table 3-6 lists the routines that perform operations on DMparams lists and the entries within them.

The sections that follow explain how to use each routine.

DMboolean dmParamsAreEqual ( const DMparams *params1,
                             const DMparams *params2 )

int dmParamsGetNumElems ( const DMparams* params )

DMstatus dmParamsCopyAllElems ( const DMparams* fromParams,
                                DMparams* toParams )

DMstatus dmParamsCopyElem ( const DMparams* fromParams,
                            const char* paramName,
                            DMparams* toParams )

const char* dmParamsGetElem ( const DMparams* params, const int index )

DMparamtype dmParamsGetElemType ( const DMparams* params,
                                  const int index )

DMparamtype dmParamsGetType ( const DMparams* params,
                              const char* paramName )

DMboolean dmParamsIsPresent  ( const DMparams* params,
                               const char* paramName )

DMstatus dmParamsScan ( const DMparams* params,
                        DMstatus (*scanFunc) ( const DMparams* params,
                                               const char* paramName,
                                               void* scanArg,
                                               DMboolean* stopScan ),
                        void* scanArg )

const char* dmParamsRemoveElem ( DMparams* params,
                                 const char* paramName)

void PrintParams( DMparams* params ) {
    int i;
    int numElems = dmParamsGetNumElems( params );
 
   for ( i = 0;  i < numElems;  i++ ) {
        const char* name = dmParamsGetElem( params, i );
        DMparamtype type = dmParamsGetElemType( params, i );
        printf( "    %20s: ", name );
        switch( type ) {
            case DM_TYPE_ENUM:
                printf( "%d", dmParamsGetEnum( params, name ) );
                break;
            case DM_TYPE_INT:
                printf( "%d", dmParamsGetInt( params, name ) );
                break;
            case DM_TYPE_STRING:
                printf( "%s", dmParamsGetString( params, name ) );
                break;
            case DM_TYPE_FLOAT:
                printf( "%f", dmParamsGetFloat( params, name ) );
                break;
            case DM_TYPE_FRACTION:
                DMfraction f = dmParamsGetFract( params, name );
                printf( "%d/%d", f.numerator, f.denominator );
                break;
            case DM_TYPE_PARAMS:
                printf( "... param list ... " );
                break;
            case DM_TYPE_TOC_ENTRY:
                printf( "... toc entry ..." );
                break;
            default:
                assert( DM_FALSE );
            }
        printf( "\n" );
    }
}

Applications that call DM Library routines must include the libdmedia header files to obtain definitions for the library; however, these files are usually included in the header file of the library you are using.

This code fragment includes all the libdmedia header files:

#include <dmedia/dmedia.h>
#include <dmedia/dm_audio.h>
#include <dmedia/dm_image.h>
#include <dmedia/dm_params.h>
#include <dmedia/dm_buffer.h>
#include <dmedia/dm_imageconvert.h>
#include <dmedia/dm_audioconvert.h>

Link with the DM Library when compiling an application that makes DM Library calls by including -ldmedia on the link line. It's likely that you'll be linking with other libraries as well, and because the linking order is usually specific, follow the linking instructions for the library you are using.

The debugging version of the DM Library checks for library usage violations by setting assertions that state the requirements for a parameter or value.

To debug your DM application, link with the debugging version of the DM Library, libdmedia.so.1, by setting your LD_LIBRARY_PATH environment variable to the directory containing the debug library before linking with -ldmedia, and then run your program. For example, use setenv LD_LIBRARY_PATH /usr/lib/debug to set the path.

Your application will abort with an error message if it fails an assertion. The message explains the situation that caused the error and, by implication or by explicit description, suggests a corrective action.

When you have finished debugging your application, you should relink with the nondebugging library, libdmedia.a, because the runtime checks imposed by the debugging library cause an undesirable size and performance overhead for a packaged application.