Bristol Wearable Computing

[ Home | Plans | Meetings | Members | Search | Papers | Links | CyberWear | LocoSoft]


Device Manager

Purpose

To allow dynamic connectivity of different devices, and to allow a means for different processes to locate communications channels between different devices.

API's


/***********************************************************/
/*Device Manager Register Functions Header                 */
/*Michael McTernan 21/6/98                                 */
/*Cyber jacket research                                    */ 
/***********************************************************/
#ifndef DEVMANREGISTERHEADER
#define DEVMANREGISTERHEADER
/*---DeviceManRegister---
PROTOTYPE                                                  */
  int DeviceManRegister(const char *DeviceName,const char *DeviceAddress,const char *ServNames[],const int ServNum); /*
DESCRIPTION
  Registers a device with the device manager.  DeviceName is
  a string that describes the device that is being registered.
  This should be descriptive, although it need not be unique.
  DeviceAddress should contain the address of the socket that
  processes can attach to to request data.  DeviceAddress
  must be unique to the device driver.
  ServName is an array of pointers to strings that contain 
  names of services that are supplied by the device driver.
  ServNum should contain the number of elements in the ServNum
  array.  It is valid to specify 0 for ServNum and NULL for 
  ServName and to then register services later using 
  ServiceRegister.   
RETURNS
  0  The applications Device Manager handle.
  -1 an error occured, the device driver should quit. 
*/

 

 

/*---DeviceManUnregister---
PROTOTYPE                                                  */
  int DeviceManUnregister();                               /*
  
DESCRIPTION
  Unregisters the previously registered device with the device
  manager.  Any registered services will automatically be 
  unregistered.  If DeviceManRegister had not previously been called,
  this function will fail and return -1 but remain stable.
RETURNS
  0  success.
  -1 an error occured.
*/

 

 

/*---ServiceRegister---
PROTOTYPE                                                  */
  int ServiceRegister(const char *ServiceName);            /*
DESCRIPTION
  Will register a service called ServiceName for the device
  previously registered with DeviceManRegister.
  
RETURNS
  0  success.
  -1 failed.
*/

 

 

/*---ServiceUnRegister---
PROTOTYPE                                                  */
  int ServiceUnRegister(const char *ServiceName);          /*
  
DESCRIPTION
  Will unregister a service called ServiceName for the device
  previously registered with DeviceManRegister.
  
RETURNS
  0  success.
  -1 failed.
*/

 

 

/*---ConnectDeviceManRegister---
PROTOTYPE                                                  */
  int ConnectDeviceManRegister();                          /* 
  
DESCRIPTION
  Connects to Device Manager server register socket, and returns
  the open file stream that permits the standard UNIX stream 
  operations including read, write and close.
RETURNS
  The file descriptor of the opened stream, or -1 if an error occurs
*/  
#endif

/***********************************************************/
/*Device Manager Queries Functions Header                  */
/*Michael McTernan 21/6/98                                 */
/*Cyber jacket research                                    */ 
/***********************************************************/
#ifndef DEVMANREQUEST
#define DEVMANREQUEST
/*---GetServiceAddress---
PROTOTYPE                                                  */
  char *GetServiceAddress(const char *Service);            /*
  
DESCRIPTION
  Returns a pointer to a string that contains the name of a
  socket where Service can be obtained from.
RETURNS
  Pointer to a strdup'ed string that is the name of the socket
  where service can be found.  In the event of error, NULL is 
  returned.                                                */
  

 

 

/*---ConnectDeviceManRequest---
PROTOTYPE                                                  */
  int ConnectDeviceManRequest();                            /* 
  
DESCRIPTION
  Connects to Device Manager server requests socket, and returns
  the open file stream that permits the standard UNIX stream 
  operations including read, write and close.
RETURNS
  The file descriptor of the opened stream, or -1 if an error occurs
*/

 

 

/*---GetServiceList---
PROTOTYPE                                                  */
  int GetServiceList(char ***ServiceList);                  /* 
  
DESCRIPTION
  Returns all the names of all services that are registered with the
  device manager.  The data can then be accessed as an array eg.
     
     char **List;
     int NumOfElements;
     
     NumOfElements=GetServiceList(&List);
     printf("%s",List[0]);
   
  Note that there actually exist NumOfElements+1 elements, but the last
  element if set to point to NULL (to make deallocation easier).
RETURNS
  -1 if an error occured, otherwise the number of elements in the
  array pointed to ServiceList.
  ServiceList will be modified to point to an array where each element
  is of type char * and points to malloc'ed memory that contains a
  service name.
  
NOTES
  It is important that the caller free's all the allocated memory
  correctly.  It is advisable for the caller to use the supplied
  function DestroyServiceList to do this.
*/ 

 

 

/*---DestroyServiceList---
PROTOTYPE                                                  */
  void DestroyServiceList(char **ServiceList);             /* 
  
DESCRIPTION
  Frees all memory allocated in the array returned from GetServiceList()
*/

 

 

/*---ConnectToService---
PROTOTYPE                                                  */
  int ConnectToService (char *ServiceName);                /* 
  
DESCRIPTION
  This function queries the Device Manager to find out the name
  of the socket where ServiceName can be found, and then creates
  a socket and connects it to the service-supplying socket.
  
RETURNS
  -1 if an error occured, otherwise open file descriptor.
 
*/  
#endif


/***********************************************************/
/*Device Manager Notification Functions Header             */
/*Michael McTernan 27/6/98                                 */
/*Cyber jacket research                                    */ 
/***********************************************************/
#ifndef DEVMANNOTIFYHEADER
#define DEVMANNOTIFYHEADER
/*---NotifyWhenAvailable---
PROTOTYPE                                                  */                                                
  int NotifyWhenAvailable(const char *ServiceName,const char *Address);/*
  
DESCRIPTION
  Takes a service name and the address of a socket to notify
  when then service becomes available.
  If the device manager cannot reply to the socket at the 
  first attempt (e.g. Socket not yet created or not listening)
  the device manager will not attempt to reply again.
  
RETURNS
  0  if the request to notify was successfully registered with 
     device manager.
  -1 otherwise. 
  
  Connects to Address and writes "+<Servicename>\n" to it when
  the service becomes available.
*/

 

 

/*---NotifyWhenUnAvailable---
PROTOTYPE                                                  */                                                
  int NotifyWhenUnAvailable(const char *ServiceName,const char *Address);/*
  
DESCRIPTION
  Takes a service name and the address of a socket to notify
  when then service becomes unavailable.
  If the device manager cannot reply to the socket at the 
  first attempt (e.g. Socket not yet created or not listening)
  the device manager will not attempt to reply again.
  
RETURNS
  0  if the request to notify was successfully registered with 
     device manager.
  -1 otherwise. 
  
  Connects to Address and writes -<Servicename>\n to it when
  the service becomes unavailable.
*/

 

 

/*---BlockUntilAvailable---
PROTOTYPE                                                     */
  int BlockUntilAvailable(const char *ServiceName[],const int NumService);/*
  
DESCRIPTION
  Takes an array of service names.  This function will not return
  (i.e. will block) until at least one the services in ServiceName[];
  becomes available.
  
RETURNS
  -1 if an error occured - the service may or may not be available.
  Array index in ServiceName of the service that has gone up*/

 

 

/*---BlockUntilChange---
PROTOTYPE                                                     */
  int BlockUntilChange(const char *ServiceName[],const int NumServices);  /*
  
DESCRIPTION
  Takes an array of service names.  The function then askes the Device
  Manager if the services are available or not, and requests for 
  notification for when the service goes up or down, depending if it is 
  currently available.
  This function will not return (i.e. will block) until at least one
  the services in ServiceName[] becomes available.
  
RETURNS
  -1 if an error occured - the service may or may not be available.
  Array index in ServiceName of the service that has changed
*/

 

 

/*---NotifyWhenLocalChange---
PROTOTYPE                                                  */                                                
  int NotifyWhenLocalChange(const char *Address);          /*
  
DESCRIPTION
  Takes a address of a socket to notify when a service name that
  starts with /LOCAL is either registered or unregistered.
  A seprate connection is made to Address for each /LOCAL service
  that changes state.
  If the device manager cannot reply to the socket at the 
  first attempt (e.g. Socket not yet created or not listening)
  the device manager will not attempt to reply again.
  
RETURNS
  0  if the request to notify was successfully registered with 
     device manager.
  -1 otherwise. 
  
  Connects to Address and writes: 
  
  -|+ <Servicename> <SP> <Device Name> <SP> <Local Socket Name> <\n>
  
  to it when a /LOCAL service becomes available or unavailable.
  The sentence will be preceeded with a - if the service has
  become unavailable, otherwise it will be preceeded with a +.
  
NOTES
  This function was created for the footbridge manager, although
  it may be used by any other process.
*/

 

 

/*---ConnectDeviceManNotify---
PROTOTYPE                                                     */
  int ConnectDeviceManNotify();                               /*
  
DESCRIPTION
  Opens a stream to the Device Manager notify service socket.
  
RETURNS
  -1 if an error occured, otherwise returns the open file descriptor*/ 
   
   
#endif

unicrest.gif (4191 bytes)

The material displayed is provided 'as is' and is subject to use restrictions.
For problems or questions regarding this web contact Cliff Randell.
Last updated: January 14, 2000.
logoep.gif (1404 bytes)
ęCopyright Hewlett-Packard 1997-2000.