/*
 * C API for libdevreg. 
 *
 * (Use libdevreg++.h for C++)
 */

#ifndef LIBDEVREG_H
#define LIBDEVREG_H

#ifdef __cplusplus
extern "C" { 
#endif

typedef void *devreg_t;
typedef void *devreg_device_t;
typedef void *devreg_devicenode_t;

/**
 * Describes the location of a device. VIRTUAL means that there is
 * no real device the user can see, like the USB root hub.
 */
typedef enum {
	INTERNAL = 0, EXTERNAL = 1, VIRTUAL = 2, UNKNOWN = 3
} devreg_location_type_t;

#ifndef NULL
#define NULL ((void*)0)
#endif


/**
 * Creates a new snapshot of the device registry by reading the given 
 * directory.
 * Use NULL to use the default, /proc/devreg (you almost always 
 * want this).
 * @param filename the devreg filename or NULL for /proc/devreg
 * @return the handle to the device regstry or NULL for error
 */
devreg_t devreg_create_registry(const char *dir);

/**
 * Frees all resources taken by the device registry.
 * @param the handle of the device registry
 */
void devreg_free_registry(devreg_t self);

/**
 * Refreshes the device-registry by re-reading the devreg directory and 
 * creating a new snapshot. This invalidates all devreg_device_t and 
 * devreg_devicefile_t handles.
 * @param the handle of the device registry
 * @return zero if an error occured. The devreg_t handle must not
 *         be used after an error, nonzero if successful
 */
int devreg_refresh(devreg_t self);

/**
 * Returns the device with the given deviceid.
 * @param the handle of the device registry
 * @param deviceid the deviceid to find
 * @param onlyExact if nonzero only exact device id matches will be 
 *                  returned
 * @param multiMatch if nonzero the function will return a device
 *        even if there are several matches. If zero and there
 *        are several matches the method will return NULL.
 * @return the first match or NULL if there was no match or
 *         there are several matches and multiMatch was
 *         turned off
 */
devreg_device_t devreg_get_device_by_id(devreg_t self,
					const char *deviceid, 
					int onlyExact,
					int multiMatch);

/**
 * Finds all devices with the given deviceid and writes them into the given 
 * list.
 * @param the handle of the device registry
 * @param deviceid the deviceid to find
 * @param devlist all matching devices will be written here if not NULL
 * @param devlist_size the maximum number of devices that can be written to 
 *                     devlist
 * @param onlyExact if nonzero only exact device id matches will be 
 *                  returned
 * @return the number of matching devices (NOT the number of devices written)
 */
int devreg_get_devices_by_id(devreg_t self,
			     const char *deviceid, 
			     devreg_device_t *devlist,
			     unsigned int devlist_size,
			     int onlyExact);

/**
 * Finds all devices that have at least one device node that implements 
 * the given interface. Each device is listed only once.
 * @param interface the interface to find
 * @param devlist all matching devices will be written here if not NULL
 * @param devlist_size the maximum number of devices that can be written to 
 *                     devlist
 * @return the number of matching devices (NOT the number of devices written)
 */
int devreg_get_devices_by_interface(devreg_t self,
				    const char *interface, 
				    devreg_device_t *devlist,
				    unsigned int devlist_size);

/**
 * Finds all root devices of the given bus and writes them into the list.
 * (Does not write the children or subdevices of the root devices).
 * @param the bus the requested bus, use NULL for all root devices
 * @param devlist all matching root devices will be written here
 * @return true if there was at least one match, false otherwise
 */
int devreg_get_devices_by_bus(devreg_t self,
			      const char *bus, 
			      devreg_device_t *devlist,
			      unsigned int devlist_size);



/**
 * Returns the parent of the device
 * @param self a handle to the device
 * @return the parent of the device or NULL if it is top-level
 */
devreg_device_t devreg_device_get_parent(devreg_device_t self);
	
/**
 * Returns the superdevice of the device
 * @param self a handle to the device
 * @return the superdevice of the device or NULL if it is 
 *         not a subdevice
 */
devreg_device_t devreg_device_get_superdevice(devreg_device_t self);

/**
 * Returns the topmost device in the subdevice hierarchy.
 * If the device does not have a superdevice, the device itself
 * is returned. When showing the user devices to select, you 
 * should usually call this method instead of presenting a 
 * subdevice to the user.
 * @param self a handle to the device
 * @return the superdevice of the device or the device itself
 */
devreg_device_t devreg_device_get_topmost_device(devreg_device_t self);
	
/**
 * Returns the number of subdevices.
 * @param self a handle to the device
 * @return the number of subdevices
 */
int devreg_device_get_subdevice_num(devreg_device_t self);
	
/**
 * Returns the Nth subdevice.
 * @param self a handle to the device
 * @param n the requested subdevice
 * @return the Nth subdevice or NULL if there is no
 *         Nth subdevice
 */
devreg_device_t devreg_device_get_subdevice(devreg_device_t self, 
					    unsigned int n);
	
/**
 * Returns the number of children.
 * @param self a handle to the device
 * @return the number of children
 */
int devreg_device_get_child_num(devreg_device_t self);
	
/**
 * Returns the Nth child.
 * @param self a handle to the device
 * @param n the requested child
 * @return the Nth child or NULL if there is no
 *         Nth child
 */
devreg_device_t devreg_device_get_child(devreg_device_t self, 
					unsigned int n);
	
/**
 * Returns the number of device nodes.
 * @param self a handle to the device
 * @return the number of device nodes
 */
int devreg_device_get_devicenode_num(devreg_device_t self);
	
/**
 * Returns the Nth device node..
 * @param self a handle to the device
 * @param n the requested device node
 * @return the Nth device node or NULL if there is no
 *         Nth device node
 */
devreg_devicenode_t devreg_device_get_devicenode(devreg_device_t self, 
						 unsigned int n);

/**
 * Returns the device's bus.
 * @return the bus as 0-terminated string
 */
const char *devreg_device_get_bus(devreg_device_t self);
	
/**
 * Returns the device's devreg directory. Use this to get 
 * bus/device specific information about the device.
 * @return the dir as 0-terminated string
 */
const char *devreg_device_get_dir(devreg_device_t self);

/**
 * Returns the device's type (empty string if unknown)
 * @return the bus as 0-terminated string
 */
const char *devreg_device_get_type(devreg_device_t self);

/**
 * Returns the device id.
 * @return the device id as 0-terminated string
 */
const char *devreg_device_get_deviceid(devreg_device_t self);

/**
 * Returns the device's model.
 * @return the model as 0-terminated string
 */
const char *devreg_device_get_model(devreg_device_t self);

/**
 * Returns the device's vendor (empty string if unknown).
 * @return the vendor as 0-terminated string
 */
const char *devreg_device_get_vendor(devreg_device_t self);

/**
 * Returns the device's location description.
 * @return the location as 0-terminated string
 */
const char *devreg_device_get_location(devreg_device_t self);

/**
 * Returns the device's location type
 * @return the location type
 */
devreg_location_type_t devreg_device_get_location_type(devreg_device_t self);


/**
 * Returns the interface (as defined in devreg_names.h)
 * of the device node.
 * @return the interface
 */
const char* devreg_devicenode_get_interface(devreg_devicenode_t self);

/**
 * If the filename is known returns the filename of the
 * device relative to the device directory (e.g. /dev).
 * @return a pointer to the filename or NULL if unknown
 */		
const char *devreg_devicenode_get_filename(devreg_devicenode_t self);


/**
 * Writes the integer contained in the given file into i
 * @param filename the name of the file
 * @param i pointer to an integer, result will be written here
 * @return 0 for error, non-zero otherwise
 */
int devreg_read_integer(const char *filename, int *i);

	
/**
 * Writes the unsigned, hexadecimal number contained in the given file 
 * into i
 * @param filename the name of the file
 * @param u pointer to an unsigned long, result will be written here
 * @return 0 for error, non-zero otherwise
 */
int devreg_read_ulong(const char *filename, unsigned long *u);


/**
 * Writes the first line contained in the given file into the buffer,
 * returns the length of the string
 * @param filename the name of the file
 * @param buf pointer where the string will be written (0-terminated)
 * @param buflen the length of the buffer
 * @return the number of character actually written (0 not included), 
 *  or negative for error
 */
int devreg_read_line(const char *filename, char *buf, int buflen);


/**
 * Reads the first line contained in the given file into the buffer
 * and matches it again the list of values. Returns the index of the read
 * string in the list or returns an erro otherwise.
 * @param filename the name of the file
 * @param values NULL-terminated list of 0-terminated strings containing the
 *        possible values of the file
 * @param e the index of the read string in the index will be written here
 * @return 0 for error, non-zero otherwise
 */
int devreg_read_enum(const char *filename, const char **values, int *e);


/**
 * Checks the existence of the given file or directory.
 * @param filename the name of the file
 * @return non-zero if exists, zero otherwise
 */
int devreg_file_exists(const char *filename);


/**
 * Reads changecount from the given file. 
 * If pfd is set and points to a number < 1 it will write the file 
 * descriptor to pfd and keep it open (so you can poll/select for new 
 * changes). 
 * If pfd is set and points to a number >=0 it will read the counter from 
 * this file (this also resets the fd so you can poll/select)
 * @param filename the name of the changecount file
 * @param pfd if not NULL the open file descriptor will be written here.
 *            if it points to a non-negative number it will be used as a
 *            file descriptor
 * @param changecount the changecount of the file will be written here
 * @return 0 for error, non-zero otherwise
 */
int devreg_read_changecount(const char *filename, 
			    int *pfd,
			    int *changecount);



#ifdef __cplusplus
}
#endif

#endif