libcdorganizer - API

Introduction

libcdorganizer is a library designed to abstract control of (hopefully) all cd organizer devices in a cross-platform library. It takes the basic functionality expected of an organizer (insert, eject, id) and implements it for whatever device it knows how to communicate with.

For developers who want to interface with the library as it exists, you want to see the function list (section 1.2).

For developers who want to extend the functionality of the library to include another device, check section 2.0.

Function List

• cdorganizer.h
• Public Functions
• const bool insert(const int slot)
• const bool eject(const int slot)
• const unsigned int getId()
• const bool ledOn()
• const bool ledOff()
• const bool reset()
• const int getStatus(char * buffer)
• const bool isValid()
• const char * getOrganizerType()const
• const int maxDiscs()const
• Protected Objects
• usb_device * myDev
• usb_dev_handle * handle
• cdorganizerFactory.h
• Public Static Function
• std::string getSupportedDevices()
• cdorganizer * createCdorganizer(struct usb_device * dev)
• std::vector <cdorganizer *> & getAllOrganizers(std::vector <cdorganizer *> & container)

Functions

In general, if a function returns a boolean value, it's a success / failure notification. Returning true means that the operation was successful. Returning false means that the operation failed. In the case of failure, recommend outputting a reason to stderr

One thing to note: For those devices that use the USB bus (all of them for now), the client program must initialize the bus. libcdorganizer does not initialize the USB bus. To make libusb initialize the bus, do the following:

• usb_init();
• usb_find_busses();
• usb_find_devices();

• cdorganizer.h

• const bool insert(const int slot)
  

  Insert a disc into the specified slot. slot should be a valid range, and should be checked for.

• const bool eject(const int slot)
  

  Eject a disc from the specified slot. slot should be a valid slot number, and should be checked for.

• const unsigned int getId()
  

  Gets a unique identifier for the device. This must be unique for each device, but does not necessarily need to be unique for each device type. This is used to differentiate between individual organizers. This, combined with the organizer type, should be used to uniquely identify the organizer

• const bool ledOn()
  

  Turns the LEDs on on the organizer. May or may not be supported by your device.

• const bool ledOff()
  

  Turns the LEDs off on the organizer. May or may not be supported by your device

• const bool reset()
  

  Sends a reset signal to the device. May or may not be supported by your device

• const int getStatus(char * buffer)
  

  Sends a request for some status. Device specific, may not be supported by your device

• const bool isValid()
  

  Checks whether the cdorganizer object is attached to a device it knows it can handle

• const char * getOrganizerType()const
  

  Gets a string that describes what model of cd organizer you have attached to this object

• const int maxDiscs()const
  

  Returns the maximum number of discs this organizer supports

• usb_device * myDev
  

  This is the usb device pointer for the device this object is attached to

• usb_dev_handle * handle
  

  This is the handle used to access the usb device this is attached to

• cdorganizerFactory.h

• std::string getSupportedDevices()
  

  Returns a comma-separated list of devices that libcdorganizer knows how to control

• cdorganizer * createCdorganizer(struct usb_device * dev)
  

  Tries to associate a cdorganizer with the device dev on the usb interface. If it recognizes dev as something it can control, it returns a new cdorganizer attached to dev. If not, it returns 0

• std::vector <cdorganizer *> & getAllOrganizers(std::vector <cdorganizer *> & container)
  

  Returns a vector of all cd organizers recognized and found on the USB bus. Populates container with these organizers, then returns it

Examples

To initialize a vector of available devices, eject slot 42, wait 5 seconds, then insert slot 42:

                #include <cdorganizer/cdorganizerFactory.h>
                #include <vector>         //To hold organizers in
                #include <usb.h>          //For usb bus initialization
                #include <iostream>       //For cout / endl
                #include <unistd.h>       //For sleep

                int main(int argc, char ** argv)
                {
                        usb_init();
                        usb_find_busses();
                        usb_find_devices();

                        std::vector <cdorganizer *> myOrganizers;
                        cdorganizerFactory::getAllOrganizers(myOrganizers);

                        for(int index(0); index < myOrganizers.size(); index++)
                        {
                                std::cout << "Found an organizer called " << myOrganizers[index]->getOrganizerType()
				<< " with ID " << myOrganizers[index]->getId() << std::endl;
                                myOrganizers[index]->eject(42);
                                sleep(5);
                                myOrganizers[index]->insert(42);
                                delete myOrganizers[index];     //Don't leak memory...
                        }
                        return 0;
                }
                

To compile, just run the standard arguments to g++, and add -lusb -lcdorganizer to it