#ifndef DEVSER_H
#define DEVSER_H

/** \file
 * \brief Device Serializer
 */

typedef struct DevSer DevSer;

/** \brief The action handler to be called
 * \param actionData the data stored with the action
 * \param lastReply the last reply or NULL when no command was
 *    sent in the last action, or the error message (when commError == 1)
 * \param commError 0: ok, 1: there was a communication error 
 * \return the command to be sent or NULL if no command has to be sent
 */
typedef char *DevActionHandler(void *actionData, char *lastReply,
                               int commError);

/** \brief Check if an action matches the call data
 * \param callData the callers data
 * \param actionData the action data
 * \return 1 on a match, 0 on no match
 */
typedef int DevActionMatch(void *callData, void *actionData);

/** \brief Kill ActionData
 * \param actionData action data
 */
typedef void DevKillActionData(void *actionData);

/** \brief possible priorities.
 * NullPRIO and NumberOfPRIO must not be used as priority
 * if an action with StartPRIO is scheduled, all other activities
 * are blocked until the action is unscheduled
 */
typedef enum {
  NullPRIO, SlowPRIO, ReadPRIO, ProgressPRIO, WritePRIO, HaltPRIO,
      StartPRIO, NumberOfPRIO
} DevPrio;

/** \brief Make a new device serializer and async connection.
 * \param con the SICS connection (for error messages)
 * \param argc the number of args for specifying the protocol
 * \param argv the args
 * \return the created device serializer or NULL on failure
 */
DevSer *DevMake(SConnection * con, int argc, char *argv[]);

/** \brief put the device serializer into debug mode
 * \param devser the device serializer
 * \param steps the number of steps to be executed or -1 for disable debugging mode
 */
void DevDebugMode(DevSer * devser, int steps);

/** \brief Kill the contents of the device serializer and its async connection.
 * 
 * The data structure itself is killed at some time later
 * \param devser the device serializer
 */
void DevKill(DevSer * devser);
/** \brief Disconnect
 * \param devser The device serializer to disconnect
 */
void DevDisconnect(DevSer * devser);

/** \brief Queue an action
 *
 * If a matching action with the same action handler
 *     exists already, no new action is queued.
 * \param devser the device serializer
 * \param actionData the action data
 * \param prio the priority
 * \param hdl the action handler
 * \param matchFunc the match function
 * \param killFunc the action data kill function (called from DevKill and
 *    after the action has finished, i.e. when hdl returned NULL) 
 *    or NULL if no kill function is needed.
 * \return 0 when not queued because a similar action is already on the queue,
 *  1 on success.
 */
int DevQueue(DevSer * devser, void *actionData, DevPrio prio,
             DevActionHandler hdl, DevActionMatch * matchFunc,
             DevKillActionData * killFunc);

/** \brief Schedule a periodic action
 *
 * If a matching action exists already,
 *   it is overwritten with a possibly changed interval and priority.
 * \param devser the device serializer
 * \param actionData the action data
 * \param prio the priority
 * \param interval the interval in seconds (0 is allowed)
 * \param hdl the action handler
 * \param matchFunc the match function (callData must be of the same type as actionData)
 * \param killFunc the action data kill function (called from DevKill and
 *    from DevUnschedule) or NULL if no kill function is needed.
 * \return 0 when this was a new action, > 0 when an action was overwritten
 */
int DevSchedule(DevSer * devser, void *actionData,
                DevPrio prio, double interval,
                DevActionHandler hdl, DevActionMatch * matchFunc,
                DevKillActionData * killFunc);

/** \brief Unschedule matching actions
 * \param devser the device serializer
 * \param actionData the callers data to be used as first argument of the match function
 * \param hdl the action handler
 * \param matchFunc the match function (callData does not need to have the same type as actionData)
 * \return the number of unscheduled actions 
 */
int DevUnschedule(DevSer * devser, void *actionData,
                  DevActionHandler hdl, DevActionMatch * matchFunc);

/** \brief remove action from the serializer
 * \param devser the device serializer
 * \param actionData the action data to be compared for a match
 */
int DevRemoveAction(DevSer * devser, void *actionData);


/** \brief Convert integer priority to text
 * \param prio
 * \return text
 */
char *DevPrio2Text(DevPrio prio);

/** \brief Convert text priority to integer
 * \param text
 * \return prio
 */
DevPrio DevText2Prio(char *text);

#endif