legacy/libburn/trunk/libburn/ddlpa.h

108 lines
3.9 KiB
C

/* ddlpa
Implementation of Delicate Device Locking Protocol level A.
Copyright (C) 2007 Thomas Schmitt <scdbackup@gmx.net>
Provided under any of the following licenses: GPL, LGPL, BSD. Choose one.
See ../doc/ddlp.txt for a description of the protocol.
*/
#ifndef DDLPA_H_INCLUDED
#define DDLPA_H_INCLUDED 1
/* An upper limit for the length of standard paths and sibling paths */
#define DDLPA_MAX_STD_LEN 15
/* An upper limit for the number of siblings */
#define DDLPA_MAX_SIBLINGS 5
struct ddlpa_lock {
/* Recorded input parameters of locking call */
char *path;
int path_is_valid;
int in_bus, in_target, in_lun;
int inbtl_is_valid;
int ddlpa_flags;
int o_flags;
/* Result of locking call */
char std_path[DDLPA_MAX_STD_LEN + 1];
int fd;
dev_t rdev;
dev_t dev;
ino_t ino;
int host, channel, id, lun, bus;
int hcilb_is_valid;
int num_siblings;
char sibling_paths[DDLPA_MAX_SIBLINGS][DDLPA_MAX_STD_LEN + 1];
int sibling_fds[DDLPA_MAX_SIBLINGS];
dev_t sibling_rdevs[DDLPA_MAX_SIBLINGS];
dev_t sibling_devs[DDLPA_MAX_SIBLINGS];
ino_t sibling_inodes[DDLPA_MAX_SIBLINGS];
/* Is NULL if all goes well. Else it may contain a text message. */
char *errmsg;
};
/** Lock a recorder by naming a device file path. Allocate a new container.
@param path Gives the file system path of the recorder
as known to the calling program.
@param o_flags flags for open(2). Do not use O_EXCL here because this
is done automatically whenever appropriate.
Advised is O_RDWR | O_LARGEFILE, eventually | O_NDELAY.
@param ddlpa_flags 0 = default behavior: the standard path will be opened
and treated by fcntl(F_SETLK)
DDLPA_OPEN_GIVEN_PATH causes the input parameter "path"
to be used with open(2) and fcntl(2).
DDLPA_ALLOW_MISSING_SGRCD allows to grant a lock
although not all three, a sg, a sr and a scd device
file have been found during sibling search. Normally
this is counted as failure due to EBUSY.
@param lockbundle gets allocated and then represents the locking state
@param errmsg if *errmsg is not NULL after the call, it contains an
error message. Then to be released by free(3).
It is NULL in case of success or lack of memory.
@return 0=success , else an errno compatible error number
*/
int ddlpa_lock_path(char *path, int o_flags, int ddlpa_flags,
struct ddlpa_lock **lockbundle, char **errmsg);
/** Lock a recorder by naming a Bus,Target,Lun number triple.
Allocate a new container.
@param bus parameter to match ioctl(SCSI_IOCTL_GET_BUS_NUMBER)
@param target parameter to match ioctl(SCSI_IOCTL_GET_IDLUN) &0xff
@param lun parameter to match ioctl(SCSI_IOCTL_GET_IDLUN) &0xff00
@param o_flags see ddlpa_lock_path().
@param ddlpa_flags see ddlpa_lock_path(). Flag DDLPA_OPEN_GIVEN_PATH
will be ignored.
@param lockbundle see ddlpa_lock_path().
@param errmsg see ddlpa_lock_path().
@return 0=success , else an errno compatible error number
*/
int ddlpa_lock_btl(int bus, int target, int lun,
int o_flags, int ddlpa_flags,
struct ddlpa_lock **lockbundle, char **errmsg);
/** Release the lock by closing all filedescriptors and freeing memory.
@param lockbundle the lock which is to be released.
*lockbundle will be set to NULL by this call.
@return 0=success , 1=failure
*/
int ddlpa_destroy(struct ddlpa_lock **lockbundle);
/** Definitions of macros used in above functions */
#define DDLPA_OPEN_GIVEN_PATH 1
#define DDLPA_ALLOW_MISSING_SGRCD 2
#endif /* DDLPA_H_INCLUDED */