NAME

libdsbmc - Client library for DSBMD

SYNOPSIS

#include <libdsbmc.h>

int
dsbmc_fetch_event(dsbmc_t *handle, dsbmc_event_t *ev);

int
dsbmc_get_devlist(dsbmc_t *handle, const dsbmc_dev_t ***list);

int
dsbmc_mount(dsbmc_t *handle, const dsbmc_dev_t *d);

int
dsbmc_unmount(dsbmc_t *handle, const dsbmc_dev_t *d, bool force);

int
dsbmc_eject(dsbmc_t *handle, const dsbmc_dev_t *d, bool force);

int
dsbmc_set_speed(dsbmc_t *handle, const dsbmc_dev_t *d, int speed);

int
dsbmc_size(dsbmc_t *handle, const dsbmc_dev_t *d);

int
dsbmc_mdattach(dsbmc_t *handle, const char *image);

int
dsbmc_set_speed_async(dsbmc_t *handle, const dsbmc_dev_t *d, int speed, void (*cb)(int, const dsbmc_dev_t *));

int
dsbmc_mount_async(dsbmc_t *handle, const dsbmc_dev_t *d, void (*cb)(int, const dsbmc_dev_t *));

int
dsbmc_unmount_async(dsbmc_t *handle, const dsbmc_dev_t *d, bool force, void (*cb)(int, const dsbmc_dev_t *));

int
dsbmc_eject_async(dsbmc_t *handle, const dsbmc_dev_t *d, bool force, void (*cb)(int, const dsbmc_dev_t *));

int
dsbmc_size_async(dsbmc_t *handle, const dsbmc_dev_t *d, void (*cb)(int, const dsbmc_dev_t *));

int
dsbmc_mdattach_async(dsbmc_t *handle, const char *image, void (*cb)(int, const dsbmc_dev_t *));

int
dsbmc_connect(dsbmc_t *handle);

int
dsbmc_get_fd(dsbmc_t *handle);

int
dsbmc_get_err(dsbmc_t *handle, const char **buf);

void
dsbmc_disconnect(dsbmc_t *handle);

void
dsbmc_free_handle(dsbmc_t *handle);

void
dsbmc_free_dev(dsbmc_t *handle, const dsbmc_dev_t *dev);

const char *‌
dsbmc_errstr(dsbmc_t *handle);

const char *‌
dsbmc_errcode_to_str(int code);

dsbmc_t *‌
dsbmc_alloc_handle(void);

dsbmc_dev_t *‌
dsbmc_dev_from_name(dsbmc_t *handle, const char *name);

dsbmc_dev_t *‌
dsbmc_dev_from_id(dsbmc_t *handle, int id);

dsbmc_dev_t *‌
dsbmc_next_dev(dsbmc_t *handle, int *idx, bool removed);

DESCRIPTION

Almost all functions operate on a handle of type dsbmc_t. dsbmc_alloc_handle() creates and initializes a handle, and returns a pointer to it. If an error occured, NULL is returned.

dsbmc_connect() establishes a connection to DSBMD, and returns 0 on success, and -1 if an error occured. If this function fails, DSBMC_ERR_CONN_DENIED is set in the error bitmask, or errno is set to any value defined in connect(2) and socket(2).

The dsbmc_disconnect() function terminates the connection to DSBMD.

dsbmc_free_handle() frees the memory used by the handle.

The dsbmc_fetch_event() function fetches the next available event, updates internal data structures, and executes callback functions. If an event is available, dsbmc_fetch_event() returns a value > 0, else 0 is returned. If an error occured, dsbmc_fetch_event() returns -1. Possible errors are DSBMC_ERR_LOST_CONNECTION, DSBMC_ERR_SYS and/or DSBMC_ERR_FATAL. Instead of CPU intensive polling, dsbmc_fetch_event() can be used together with select() by passing the file descriptor retrieved by dsbmd_get_fd().

The dsbmc_get_devlist() fucntion sets the given pointer to the internal list of dsbmc_dev_t *‌ objects. The number of objects is returned.

The dsbmc_get_fd() function returns the file descriptor of the socket which is connected to DSBMD. Its ONLY purpose is to use it with select().

The dsbmc_mount() function mounts the device represented by the given object. The function blocks until a reply from DSBMD is received or an error occured. On success dsbmc_mount() returns 0. If mounting failed, an error code > 0 is returned, which can be one of DSBMC_ERR_ALREADY_MOUNTED, DSBMC_ERR_NO_MEDIA DSBMC_ERR_PERMISSION_DENIED, DSBMC_ERR_DEVICE_BUSY, DSBMC_ERR_NO_SUCH_DEVICE, DSBMC_ERR_UNKNOWN_FILESYSTEM, DSBMC_ERR_UNKNOWN_ERROR, DSBMC_ERR_MNTCMD_FAILED. If an error occured, -1 is returned, and the error bitmask is set accordingly.

The dsbmc_unmount() function unmounts the device represented by the given object. If 'force' is true, unmounting will be enforced even if the device is busy. The function blocks until a reply from DSBMD is received or an error occured. On success dsbmc_unmount() returns 0. If unmounting failed, an error code > 0 is returned, which can be DSBMC_ERR_NOT_MOUNTED, DSBMC_ERR_DEVICE_BUSY, or an errno number. If an error occured, -1 is returned, and the error bitmask is set accordingly.

The dsbmc_eject() function ejects the device represented by the given object. If 'force' is true, ejecting will be enforced even if the device is busy. The function blocks until a reply from DSBMD is received or an error occured. On success dsbmc_eject() returns 0. If ejecting failed, an error code > 0 is returned, which can be DSBMC_ERR_NOT_EJECTABLE, DSBMC_ERR_DEVICE_BUSY, or an errno number. If an error occured, -1 is returned, and the error bitmask is set accordingly.

The dsbmc_set_speed() function sets the reading speed of the optical device represented by the given object. The function blocks until a reply from DSBMD is received or an error occured. On success dsbmc_set_speed() returns 0. If it failed, an error code > 0 is returned, which can be ERR_INVALID_ARGUMENT, or an errno number. If an error occured, -1 is returned, and the error bitmask is set accordingly.

The dsbmc_size() function queries the storage capacity, the number of used and free bytes of the device represented by the given object.

The dsbmc_mdattach() function asks DSBMD to create a memory disk to access the given disk image. The function blocks until a reply from DSBMD is received or an error occured. On success dsbmc_mdattach() returns 0, else an error code > 0 is returned, which can be DSBMC_ERR_NOT_A_FILE, DSBMC_ERR_PERMISSION_DENIED, or an errno number. If an error occured, -1 is returned, and the error bitmask is set accordingly.

The _async() variant of dsbmc_mount(), dsbmc_unmount(), dsbmc_eject(), dsbmc_set_speed(), and dsbmc_mdattach() return 0, and the given callback function will be executed by dsbmd_fetch_event() as soon as a command-reply code is received. If an error occured, -1 is returned, and the error bitmask is set accordingly.

If the DSBMC_EVENT_DEL_DEVICE event was received, the device object should be removed from the list using dsbmc_free_dev() if it is no longer needed.

If one of the functions failed with an error, the function dsbmc_get_err() can be used to retrieve the error bitmask. If errstr is not NULL, it is set to the corresponding error message.

The function dsbmc_errstr() returns the last error message.

The dsbmc_errcode_to_str() function translates a DSBMD error-code into a string.

The dsbmc_dev_from_name() function returns a pointer to the device object matching the given device name, or NULL if there was no match.

The dsbmc_dev_from_id() function returns a pointer to the device object matching the given ID, or NULL if there was no match.

The dsbmc_next_dev() function returns the next device from the device list, starting from *idx, and increases the content of the given index pointer. If removed is false, removed devices are ignored. If the end of the list is reached, NULL is returned.

THREADS

libdsbmc can be used together with threads. However, access to a single handle from multiple threads must be synchronized, e.g. by using a mutex.

OBJECTS

Device object definition:

typedef struct dsbmc_dev_s {
	uint8_t cmds;			/* Supported commands. */
#define DSBMC_CMD_MOUNT			(1 << 0x00)
#define DSBMC_CMD_UNMOUNT		(1 << 0x01)
#define DSBMC_CMD_EJECT			(1 << 0x02)
#define DSBMC_CMD_PLAY			(1 << 0x03)
#define DSBMC_CMD_OPEN			(1 << 0x04)
#define DSBMC_CMD_SPEED			(1 << 0x05)
#define DSBMC_CMD_SIZE			(1 << 0x06)
#define DSBMC_CMD_MDATTACH		(1 << 0x07)
	uint8_t type;
#define DSBMC_DT_HDD			0x01
#define DSBMC_DT_USBDISK		0x02
#define DSBMC_DT_DATACD			0x03
#define	DSBMC_DT_AUDIOCD		0x04
#define	DSBMC_DT_RAWCD			0x05
#define	DSBMC_DT_DVD			0x06
#define	DSBMC_DT_VCD			0x07
#define	DSBMC_DT_SVCD			0x08
#define	DSBMC_DT_FLOPPY			0x09
#define DSBMC_DT_MMC			0x0a
#define DSBMC_DT_MTP			0x0b
#define DSBMC_DT_PTP			0x0c
	int	 id;			/* Unique ID */
	char	 *dev;			/* Device name */
	char	 *volid;		/* Volume ID */
	char	 *mntpt;		/* Mount point */
	char	 *fsname;		/* Filesystem name */
	bool	 mounted;		/* Whether drive is mounted. */
	bool	 removed;		/* Whether device was removed */
	uint8_t	 speed;			/* CD/DVD reading speed */
	uint64_t mediasize;		/* For "size" command. */
	uint64_t free;			/* 	 ""	       */
	uint64_t used;			/* 	 ""	       */
} dsbmc_dev_t;

Event object definition:

typedef struct dsbmc_event_s {
	int type;			/* Event type */
	int code;			/* Error code */
	dsbmc_dev_t *dev;		/* Device object */
} dsbmc_event_t;

ERROR CODES

dsbmc_get_err() returns the following error codes as bitmask:

DSBMC_ERR_SYS

Syscall failed

DSBMC_ERR_FATAL

Fatal error. Continuing the program is probably not possible.

DSBMC_ERR_LOST_CONNECTION

Connection to DSBMD lost.

DSBMC_ERR_CONN_DENIED

The client has no permission to connect to DSBMD.

DSBMC_ERR_INVALID_DEVICE

A NULL pointer or a pointer to a removed device object was passed.

DSBMC_ERR_CMDQ_BUSY

The max. number of commands to be send asynchronously was exceeded.

DSBMC_ERR_COMMAND_IN_PROGRESS

An attempt was made to send a command while there are still commands in the command queue.

Possible error codes of dsbmd events are:

DSBMC_ERR_ALREADY_MOUNTED, DSBMC_ERR_PERMISSION_DENIED, DSBMC_ERR_NOT_MOUNTED, DSBMC_ERR_DEVICE_BUSY, DSBMC_ERR_NO_SUCH_DEVICE, DSBMC_ERR_MAX_CONN_REACHED, DSBMC_ERR_NOT_EJECTABLE, DSBMC_ERR_UNKNOWN_COMMAND, DSBMC_ERR_UNKNOWN_OPTION, DSBMC_ERR_SYNTAX_ERROR, DSBMC_ERR_NO_MEDIA, DSBMC_ERR_UNKNOWN_FILESYSTEM, DSBMC_ERR_UNKNOWN_ERROR, DSBMC_ERR_MNTCMD_FAILED, DSBMC_ERR_NOT_A_FILE