PSI sics-cvs-psi-2008-10-02

devser.h

@@ -0,0 +1,123 @@
+#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
+ * \return the command to be sent or NULL if no command has to be sent
+ */
+typedef char *DevActionHandler(void *actionData, char *lastReply);
+
+/** \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
+ */
+typedef enum {
+  NullPRIO, SlowPRIO, ReadPRIO, ProgressPRIO, WritePRIO, HaltPRIO, 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 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.
+ */
+void 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 callData the callers data to be 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