Xface Core Library: XFaceApp::Task Class Reference

XFace / XEngine / XMath

XFaceApp::Task Class Reference

#include <Task.h>

List of all members.

Detailed Description

Koray Balci
For controlling Xface, clients have one of two ways. First is the use of classes implemented as usual, and the second is using the Task mechanism. We define a set of Task types, and this class stores the properties of these tasks. Every Task object has a name, set of parameters, an ID and owner ID. Name is a string representing the actual role of the object. You can find more information about Task names/types in TaskDictionary class documentation. Every Task object has also a set of string parameters depending on the Task type it belongs to. ID is supposed to be a unique number representing the Task instance. It might have been assigned automatically during construction, but we chose it to be assigned externally for the time being. Owner ID represents the thread/application which has created and issued this task to Xface. This value is used for feedback notification (more on this: Notification class) mechanism.

Here is a sample of usage from XfaceClient, where we issue a "resume playback" task through TCP/IP;

        // we create a task with the client Id and a unique task ID.
        Task task("RESUME_PLAYBACK", m_clientId, ++m_taskCount + 1000000*m_clientId);
        // following function translates the Task to XML string 
        std::string msg = XMLUtils::xmlify(task);
        // Here we send the string through network
        m_pSocket->Write(msg.c_str(), msg.size() + 1);

On the other hand, if this is a standalone application, or we have direct access to XFaceApp::TaskHandlerBase derived class, we can issue the Task as follows;

        Task playtask("RESUME_PLAYBACK");
        m_pApp->newTask(playtask);      // m_pApp is a pointer to a TaskHandlerBase derived class instance.

Note that, we do not have to (and in fact should not) pass owner id and task id for the Task object, because, it is defaulted to 0, and this way we prevent creating/sending Notification messages. After all, the latter use is only for the thread that has access to the TaskHandlerBase class. A class derived from TaskHandlerBase, tailored for your own purposes can implement event notification mechanism much more efficiently.

Future: In the future versions, we can add plenty of things to this mechanism. Parameters can be in types other than string. ID can be assigned automatically and invisibly, however this can create a set of new problems, not sure.. And finally, we can implement a whole class hierarchy instead of using strings for naming Task types. For the time being, the system is sufficient for our needs.

Public Member Functions

void clearParams ()
 Clears the parameters.
unsigned short getParamCount () const
 Returns the number of currently pushed parameters.
void setName (const std::string &name)
 Sets the name, first checks the existence of the Task by calling TaskDictionary::isTask.
const std::string & getName () const
 Returns the name of the Task.
void pushParameter (const std::string &param)
 Pushes a new parameter string to the parameter collection.
std::string getParameter (unsigned int id) const
 Returns the parameter indexed by id.
unsigned short getOwnerID () const
 Returns the owner ID.
void setOwnerID (unsigned short id=0)
 Sets the owner ID.
unsigned int getID () const
 Gets Task ID.
void setID (unsigned int id=0)
 Sets Task ID.
 Task (const std::string &name, unsigned short owner=0, unsigned int id=0)

Constructor & Destructor Documentation

XFaceApp::Task::Task const std::string &  name,
unsigned short  owner = 0,
unsigned int  id = 0

Note that during construction, task name is checked against TaskDictionary, so, if an invalid task name is inserted, the name of the task is empty string. If you are not sure about the validity of the task name, try calling TaskDictionary::isTask beforehand.

Member Function Documentation

std::string XFaceApp::Task::getParameter unsigned int  id  )  const

Gets the parameter indexed at id. If an invalid (out of bounds) index is passed an empty string is returned.

The documentation for this class was generated from the following files:
Generated on Mon Aug 28 15:39:26 2006 for Xface Core Library by  doxygen 1.4.6-NO