libmtp: The object management API.

- Main Page
- Modules
- Data Structures
- Files
- Directories
- Examples

# The object management API.

## Functions
char * | LIBMTP_Get_String_From_Object (LIBMTP_mtpdevice_t *, const uint32_t, const uint32_t)
uint32_t | LIBMTP_Get_U32_From_Object (LIBMTP_mtpdevice_t *, const uint32_t, const uint32_t, const uint32_t)
uint16_t | LIBMTP_Get_U16_From_Object (LIBMTP_mtpdevice_t *, const uint32_t, const uint32_t, const uint16_t)
int | LIBMTP_Set_Object_String (LIBMTP_mtpdevice_t *, const uint32_t, const uint32_t, char const *const)
int | LIBMTP_Set_Object_U32 (LIBMTP_mtpdevice_t *, const uint32_t, const uint32_t, const uint32_t)
int | LIBMTP_Set_Object_U16 (LIBMTP_mtpdevice_t *, const uint32_t, const uint32_t, const uint16_t)
int | LIBMTP_Get_Object_References (LIBMTP_mtpdevice_t *, const uint32_t, uint32_t **, uint32_t *)
int | LIBMTP_Set_Object_References (LIBMTP_mtpdevice_t *, const uint32_t, uint32_t const *const, const uint32_t)
LIBMTP_object_t * | LIBMTP_Make_List (LIBMTP_mtpdevice_t *, uint32_t *, uint32_t, uint32_t *, uint32_t)
LIBMTP_object_t * | LIBMTP_Find_Object (LIBMTP_object_t *, const uint32_t)
void | LIBMTP_Dump_List (LIBMTP_object_t *)
LIBMTP_object_t * | LIBMTP_new_object_t (void)
void | LIBMTP_destroy_object_t (LIBMTP_object_t *, uint32_t)
int | LIBMTP_Delete_Object (LIBMTP_mtpdevice_t *, uint32_t)

## Function Documentation

int LIBMTP_Delete_Object | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t | object_id |
| ) |  |  |

This function deletes a single file, track, playlist or any other object off the MTP device, identified by an object ID.

Parameters:

  | device | a pointer to the device to delete the file or track from.
  | item_id | the item to delete.

Returns:
  0 on success, any other value means failure.

void LIBMTP_destroy_object_t | ( | LIBMTP_object_t * | object,
|  | uint32_t | recursive |
| ) |  |  |

This deletes the memory for an object structure and makes use of the registered destructor for the object type data.

Parameters:

  | object | object structure to destroy
  | recurse | indicate if the call should recursively delete the object. Specify 1 for recursion.

See also:
  LIBMTP_new_object_t()

void LIBMTP_Dump_List | ( | LIBMTP_object_t * | list | ) |

Debug function that dumps out some textual representation of an object list.

Parameters:

  | list | object list returned from LIBMTP_Make_List

See also:
  LIBMTP_Make_List()

LIBMTP_object_t* LIBMTP_Find_Object | ( | LIBMTP_object_t * | objectlist,
|  | uint32_t | id |
| ) |  |  |

Helper function. Returns a folder structure for a specified id.

Parameters:

  | objectlist | list of objects to search id of object to look for

Returns:
  a object or NULL if not found

int LIBMTP_Get_Object_References | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | object_id,
|  | uint32_t ** | items,
|  | uint32_t * | len |
| ) |  |  |

Gets an array of object ids associated with a specified object

Parameters:

  | device | a pointer to an MTP device.
  | object_id | Object reference
  | items | array of unsigned 32-bit integers
  | len | length of array

Returns:
  0 on success, any other value means failure

char* LIBMTP_Get_String_From_Object | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | object_id,
|  | uint32_t const | attribute_id |
| ) |  |  |

Retrieves a string from an object

Parameters:

  | device | a pointer to an MTP device.
  | object_id | Object reference
  | attribute_id | PTP attribute ID

Returns:
  valid string or NULL on failure. The returned string must bee `free()`:ed by the caller after use.

uint16_t LIBMTP_Get_U16_From_Object | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | object_id,
|  | uint32_t const | attribute_id,
|  | uint16_t const | value_default |
| ) |  |  |

Retrieves an unsigned 16-bit integer from an object attribute

Parameters:

  | device | a pointer to an MTP device.
  | object_id | Object reference
  | attribute_id | PTP attribute ID
  | value_default | Default value to return on failure

Returns:
  a value

uint32_t LIBMTP_Get_U32_From_Object | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | object_id,
|  | uint32_t const | attribute_id,
|  | uint32_t const | value_default |
| ) |  |  |

Retrieves an unsigned 32-bit integer from an object attribute

Parameters:

  | device | a pointer to an MTP device.
  | object_id | Object reference
  | attribute_id | PTP attribute ID
  | value_default | Default value to return on failure

Returns:
  the value

LIBMTP_object_t* LIBMTP_Make_List | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t * | filter,
|  | uint32_t | filter_len,
|  | uint32_t * | exclusions,
|  | uint32_t | exclusion_len |
| ) |  |  |

This returns a list of objects on the current MTP device, selected by a filter based on PTP object ID:s.

Parameters:

  | device | a pointer to the device to get the object listing for.
  | filter | array of unsigned 32-bit integers specifying which types to include in the list
  | filter_len | length of filter array in 32-bit words
  | exclusions | array of unsigned 32-bit integers specifying which types to exclude from the list
  | exclusion_len | length of exclusion array

Returns:
  a list of objects

See also:
  LIBMTP_destroy_object_t()

LIBMTP_object_t* LIBMTP_new_object_t | ( | void |  | ) |

This creates a new MTP object structure and allocates memory for it. Notice that if you add strings to this structure they will be freed by the corresponding `LIBMTP_destroy_object_t` operation later, so be careful of using strdup() when assigning strings, e.g.:

     LIBMTP_object_t *object = LIBMTP_new_object_t();
     object->name = strdup(namestr);
     ....
     LIBMTP_destroy_object_t(file);

Returns:
  a pointer to the newly allocated structure.

See also:
  LIBMTP_destroy_object_t()

int LIBMTP_Set_Object_References | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | object_id,
|  | uint32_t const *const | items,
|  | uint32_t const | len |
| ) |  |  |

Sets an array of object ids associated with a specified object

Parameters:

  | device | a pointer to an MTP device.
  | object_id | Object reference
  | items | array of unsigned 32-bit integers
  | len | length of array

Returns:
  0 on success, any other value means failure

int LIBMTP_Set_Object_String | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | object_id,
|  | uint32_t const | attribute_id,
|  | char const *const | string |
| ) |  |  |

Sets an object attribute from a string

Parameters:

  | device | a pointer to an MTP device.
  | object_id | Object reference
  | attribute_id | PTP attribute ID
  | string | string value to set

Returns:
  0 on success, any other value means failure

int LIBMTP_Set_Object_U16 | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | object_id,
|  | uint32_t const | attribute_id,
|  | uint16_t const | value |
| ) |  |  |

Sets an object attribute from an unsigned 16-bit integer

Parameters:

  | device | a pointer to an MTP device.
  | object_id | Object reference
  | attribute_id | PTP attribute ID
  | value | 16-bit unsigned integer to set

Returns:
  0 on success, any other value means failure

int LIBMTP_Set_Object_U32 | ( | LIBMTP_mtpdevice_t * | device,
|  | uint32_t const | object_id,
|  | uint32_t const | attribute_id,
|  | uint32_t const | value |
| ) |  |  |

Sets an object attribute from an unsigned 32-bit integer

Parameters:

  | device | a pointer to an MTP device.
  | object_id | Object reference
  | attribute_id | PTP attribute ID
  | value | 32-bit unsigned integer to set

Returns:
  0 on success, any other value means failure