libnjb: The datafile tag (metadata) retrieveal API

libnjb 2.2.7

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

Macros | Functions
The datafile tag (metadata) retrieveal API

## Macros
#define | NJB_Get_File NJB_Get_Track
#define | NJB_Get_File_fd NJB_Get_Track_fd

## Functions
void | NJB_Reset_Get_Datafile_Tag (njb_t *njb)
njb_datafile_t * | NJB_Get_Datafile_Tag (njb_t *njb)
void | NJB_Datafile_Destroy (njb_datafile_t *df)
int | NJB_Send_File (njb_t *njb, const char *path, const char *name, const char *folder, NJB_Xfer_Callback *callback, void *data, u_int32_t *fileid)
int | NJB_Delete_Datafile (njb_t *njb, u_int32_t fileid)
int | NJB_Create_Folder (njb_t *njb, const char *name, u_int32_t *folderid)

## Detailed Description

## Function Documentation

int NJB_Create_Folder | ( | njb_t * | njb,
|  | const char * | name,
|  | u_int32_t * | folderid
| ) |  |

This function creates a new folder on the device, if the device supports folder creation.

Parameters

  njb | a pointer to the `njb_t` jukebox object to use
  name | the name of the new folder to create
  folderid | a pointer to a variable that will hold the new item ID for the folder if it is successfully created.

Returns
  0 on success, -1 on failure. Notice that a case of failure is when an NJB1 is used, so this should normally result in "not implemented" error.

References njb_struct::device_type, and NJB_DEVICE_NJB1.

void NJB_Datafile_Destroy | ( | njb_datafile_t * | df | ) |

Destroys a datafile struct.

Parameters

  df | the datafile struct to destroy

References njb_datafile_struct::filename, and njb_datafile_struct::folder.

Referenced by datafile_unpack(), and NJB_Send_File().

int NJB_Delete_Datafile | ( | njb_t * | njb,
|  | u_int32_t | fileid
| ) |  |

This deletes a datafile from the device.

Parameters

  njb | a pointer to the `njb_t` jukebox object to use
  fileid | the file ID for the file to delete

Returns
  0 on success, -1 on failure

Examples:
  delfile.c.

References njb_struct::device_type, EO_BADCOUNT, and NJB_DEVICE_NJB1.

njb_datafile_t* NJB_Get_Datafile_Tag | ( | njb_t * | njb | ) |

This gets a datafile tag from the device. The device should first be rewound using the `NJB_Reset_Get_Datafile_Tag()` function. The tag is newly allocated and should be destroyed with `NJB_Datafile_Destroy()` after use.

Parameters

  njb | a pointer to the `njb_t` object to get datafiles from

Returns
  a datafile tag or NULL if the last datafile tag has already been returned

See Also
  NJB_Reset_Get_Datafile_Tag()

Examples:
  files.c, and getfile.c.

References njb_struct::device_type, NJB_DEVICE_NJB1, and njb_struct::protocol_state.

void NJB_Reset_Get_Datafile_Tag | ( | njb_t * | njb | ) |

This resets the datafile metadata retrieveal function. The datafile tags can then be retrieved one by one using the `NJB_Get_Datafile_Tag()` function.

Typical usage:

    njb_t *njb;
    njb_datafile_t *df;

    NJB_Reset_Get_Datafile_Tag(njb);
    while ( (df = NJB_Get_Datafile_Tag(njb)) != NULL ) {
       // Do something with all the datafiles...
       NJB_Datafile_Destroy(df);
    }

Parameters

  njb | a pointer to the `njb_t` object to reset the datafile retrieveal pointer for

See Also
  NJB_Get_Datafile_Tag()

Examples:
  files.c, and getfile.c.

References njb_struct::device_type, njb3_reset_get_datafile_tag(), NJB_DEVICE_NJB1, and njb_struct::protocol_state.

int NJB_Send_File | ( | njb_t * | njb,
|  | const char * | path,
|  | const char * | name,
|  | const char * | folder,
|  | NJB_Xfer_Callback * | callback,
|  | void * | data,
|  | u_int32_t * | fileid
| ) |  |

This function sends a datafile to the device (downloads), optionally using a folder name.

Parameters

  njb | a pointer to the `njb_t` object to send the file to
  path | a path to the file that shall be downloaded.
  name | a filename to use for this file on the device. Should only be the basename, excluding any folder name(s).
  folder | a folder name to use for this file on the device. Not all devices support folders, so this might be ignored. A folder name must begin and end with backslash () and have levels of hierarchy separated by backslashes too, like this: "\foo\bar\fnord\".
  callback | a function that will be called repeatedly to report progress during transfer, used for e.g. displaying progress bars. This may be NULL if you don't like callbacks.
  data | a voluntary parameter that can associate some user-supplied data with each callback call. It is OK to set this to NULL of course.
  fileid | a pointer to a variable that will hold the new file ID when the operation is finished.

Returns
  0 on success, -1 on failure.

Examples:
  sendfile.c.

References _file_size(), _file_time(), datafile_pack(), datafile_pack3(), datafile_set_folder(), datafile_set_name(), datafile_set_size(), datafile_set_time(), njb_struct::device_type, EO_INVALID, EO_SRCFILE, EO_TOOBIG, EO_XFERDENIED, NJB_Datafile_Destroy(), NJB_DEVICE_NJB1, and njb_get_disk_usage().