---
name: "njb_datatagapi"
section: "3"
platform: "linux"
package: "libnjb-doc"
version: "2.2.5-4.3"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/njb_datatagapi"
---

# njb\_datatagapi(3)

## NAME

The datafile tag (metadata) retrieveal API -

### Defines

\#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)\

## 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().

## Author

Generated automatically by Doxygen for libnjb from the source code.