PMPlib helper API
[PMPlib APIs]

The PMPlib Helper API provides the utility for choosing a suitable PMPlib driver from a number of installed drivers. More...

Typedefs

typedef tag_pmplib_t pmplib_t
 The structure for the PMPlib Helper API.

Functions

PMPAPI result_t pmplib_init (pmplib_t **ptr_pmplib)
 Initialize the PMPlib helper library.
PMPAPI result_t pmplib_finish (pmplib_t *pmplib)
 Uninitialize the PMPlib helper library.
PMPAPI result_t pmplib_create (pmplib_t *pmplib, pmp_t **ptr_pmp, const ucs2char_t *path_to_device, const char *id)
 Query a driver and create a pmp_t instance.
PMPAPI result_t pmplib_enumerate_devid (pmplib_t *pmplib, pmplib_enumerate_devid_callback_t callback, void *instance)
 Enumerate device identifiers of the installed drivers.

Detailed Description

The PMPlib Helper API provides the utility for choosing a suitable PMPlib driver from a number of installed drivers.

Because the PMPlib project implements a number of drivers for different portable media devices, an application must choose a suitable driver that matches to the target device. By using this API, an application can query a driver suitable for the portable media device specified by the mount location (root directory of the device) and/or the string identifier of a driver. An application can also enumerate the string identifiers of the drivers available in the system.

An application must call pmplib_init() function to initialize the API and obtain the pointer to a pmplib_t instance that is used for subsequent calls of the API. The application can query an interface to a PMPlib driver by using pmplib_create() function. A list of installed device identifiers is obtained by receiving callback notifications invoked by pmplib_enumerate_devid() function. The application must terminate this API by calling pmplib_finish() function.

This is an example of querying an interface to the driver that matches to the device connected to the mount point (Win32 path "D:\"):

 #include <pmplib/ucs2char.h>
 #include <pmplib/pmp.h>
 
 int main(int argc, char *argv[])
 {
     result_t ret = 0;
     pmp_t* pmp = NULL;
     pmplib_t* pmplib = NULL;
     static const ucs2char_t path[] = {'D',':','\\',0};

     // Initialize the PMPlib Helper API.
     if ((ret = pmplib_init(&pmplib)) != 0) {
         // Failed to initialize the API.
         goto error_exit;
     }

     // Query an interface to the PMPlib driver suitable for the path.
     if ((ret = pmplib_create(pmplib, &pmp, path, NULL)) != 0) {
         // Failed to find a suitable driver.
         goto error_exit;
     }
     
     // Processing with the driver.
     ...

     // Release the driver.
     pmp->release(pmp);

     // Terminate the helper API.
     pmplib_finish(pmplib);
     return 0;

 error_exit:
     // Error handling.
     ...
     return 1;
 }

Typedef Documentation

typedef struct tag_pmplib_t pmplib_t

The structure for the PMPlib Helper API.

An application should use a pointer to this structure as a handle value for this API. Call pmplib_init() function to obtain a pointer to this structure and pmplib_finish() function to terminate this API. Access to a member in this structure is prohibited since it is reserved for the internal use of the library only.

Definition at line 932 of file pmp.h.

Function Documentation

PMPAPI result_t pmplib_create ( pmplib_t *  pmplib,
pmp_t **  ptr_pmp,
const ucs2char_t *  path_to_device,
const char *  id 
)

Query a driver and create a pmp_t instance.

This function queries the driver suitable for the portable media device specified by the mount location and/or identifier, and returns the interface to the driver (pmp_t instance). An application must specify parameter path_to_device. If parameter id is not NULL, this function obtains the interface to the driver with the device identifier specified in id parameter. If the parameter id is NULL, this function tries to recognize the model of the device based on the content of the files located under path_to_device. If successful, the interface to the driver will be returned in the pmp argument.

Parameters:
pmplib The pointer to the pmplib_t instance.
ptr_pmp The pointer to the buffer to receive the pointer to the driver interface (pmp_t instance).
path_to_device A UCS-2 string representing the location of the target device. This parameter cannot be NULL.
id A C-string representing the device identifier of the target device. If this argument is NULL, this function tries to recognize the model of the device based on the location (path_to_device).
Return values:
result_t The status code.
Assertions: 
 pmplib != NULL 

 ptr_pmp != NULL 

 path_to_device != NULL

PMPAPI result_t pmplib_enumerate_devid ( pmplib_t *  pmplib,
pmplib_enumerate_devid_callback_t  callback,
void *  instance 
)

Enumerate device identifiers of the installed drivers.

This function enumerates the device identifiers of the installed drivers, and invokes the callback function for each identifier.

Parameters:
pmplib The pointer to the pmplib_t instance.
callback The pointer to the callback function to receive device identifiers.
instance A user-defined instance value. The callback function will receive the same value.
Return values:
result_t The status code.
Assertions: 
 pmplib != NULL 

 callback != NULL

PMPAPI result_t pmplib_finish ( pmplib_t *  pmplib  ) 

Uninitialize the PMPlib helper library.

This function detatch the drivers loaded by pmplib_init() function.

Parameters:
pmplib The pointer to the pmplib_t instance.
Return values:
result_t The status code.
Assertions: 
 ptr_pmplib != NULL
Note:
Call this function to terminate this API.

PMPAPI result_t pmplib_init ( pmplib_t **  ptr_pmplib  ) 

Initialize the PMPlib helper library.

This function loads the drivers installed in the system to prepare them.

Return values:
ptr_pmplib The pointer to the buffer to receive the pointer to the pmplib_t instance initialized by this function.
result_t The status code.
Assertions: 
 ptr_pmplib != NULL
Note:
Call this function before using any other functions in this API.