API Status Request

API DOCUMENTATION

STATUS REQUEST:

CREATION:

• StatusRequest()

CONTROL:

• void setWaiting(unsigned int aCount = 1)
• bool signal(int aStatus)
• bool signalComplete (int aStatus)
• bool pending()
• bool completed()
• int getStatus()
• int getCount()

TIMEOUT:

• void setTimeout(unsigned long aTimeout)
• unsigned long getTimeout()
• void resetTimeout()
• long untilTimeout()

---

• StatusRequest()

StatusRequest();

Default constructor. Takes no parameters. Creates Status Request object, which is assigned a status of “completed” on creation.

• void setWaiting(unsigned int aCount = 1)

void setWaiting(unsigned int aCount = 1)

Activates Status Request object. By default each object is set to wait on one event only, however, if aCount is supplied, Status Request can wait on multiple events. For instance, setWaiting(3) will wait on three signals. An example could be waiting for completion of measurements from 3 sensors.

• bool signal(int aStatus)

bool signal(int aStatus)

Signals completion of the event to the Status Request object, and passes a completion code, which could be interrogated later.
Note: passing a negative status code to the status request object is considered reporting an error condition, and will complete the status request regardless of how many outstanding signals it is still waiting for.
Note: only the latest status code is kept.

• bool signalComplete (int aStatus)

bool signalComplete (int aStatus)

Signals completion of ALL events to the Status Request object, and passes a completion code, which could be interrogated later. The status request completes regardless of how many events it is still waiting on.

• bool pending()

bool pending()

Returns true if status request is still waiting for event or events to happen.

• bool completed()

bool completed()

Returns true if status request event has completed.

• int getStatus()

int getStatus()

Returns the status code passed to the status request object by the signal() and signalComplete() methods.
Any positive number is considered a successful completion status.
A 0 (zero) is considered a default successful completion status.
Any negative number is considered an error code and unsuccessful completion of a request.

• int getCount()

int getCount()

Returns the count of events not yet completed. Typically by default a StatusRequest object only waits on 1 event. However, in the situations where a StatusRequest object is waiting on multiple events, a number of events not yet completed is returned by this method.

• void setTimeout(unsigned long aTimeout)

void setTimeout(unsigned long aTimeout)

Sets the timeout for this StatusRequest object. When enabled the activated StatusRequest object will complete with the code TASK_SR_TIMEOUT (-99) if no other process calls its signal() or signalComplete() method before the timeout occurs.

• unsigned long getTimeout()

unsigned long getTimeout()

Returns the timeout interval for the current StatusRequest object. This is the full original interval, not the remaining time.

• void resetTimeout()

void resetTimeout()

Resets the current timeout counter to the original value. The timeout countdown starts from the beginning again.

• long untilTimeout()

long untilTimeout()

Returns the number of milliseconds (microseconds) until timeout. The value could be negative if the timeout has already occurred.