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

---