Timer

The timer module allows the application to set timers and cancel them if not needed anymore.

Each timer is identified by a timer ID that is issued by the timer module. Each timer also has an “owner” user who is notified via the in-app notification upon expiry or cancellation of the timer.

The owner is the user who sets/adds/starts the timer - however, right now, it’s used only for delivering notifications and not for controlling access to the timer itself. What it means is that any other user can also cancel a timer if the timer ID is known to him.

There are two types of timers supported:

• One-shot
• Periodic

The names themselves are pretty self-explanatory.

A one-shot timer is removed from the system after it expires and cannot be referenced after that using the timer ID that was issued.

A periodic timer stays in the system and keeps generating “completed” events upon end of period.

Along with these two timer classes, the timer module also provides an API to get the current system time. This is available as both a UNIX timestamp as well as a formatted string of the type

YYYY-MM-DD HH:MM:SS

API: Get Current Time

Get Current Time API

URL: {BASE_URL}/app/<APP_ID>/timer/current_time

Request Method: HTTP GET

Parameter	Mandatory	Type	Description
APP_ID	Yes	Alpha-numeric	The application ID issued by the Playblazer platform when the app was created
secret_key	Yes	Alpha-numeric	The secret key issued by the Playblazer platform when the app was created
fmt	No	String	One of (json | xml) - the format of output

Example

URL Call:

curl "http://api.playblazer.com/v1/app/1/timer/current_time?secret_key=cb8d878989b9478e96d1b1574a1bf4ec"

Output:

{
   "status": "ok",
    "timestamp": 1357916799,
    "time_str": "2013-01-11 20:36:39 "
}

API: Add Timer

Add Timer API

URL: {BASE_URL}/app/<APP_ID>/timer/<MODE>/<USER_ID>/add

Request Method: HTTP POST

Parameter	Mandatory	Type	Description
APP_ID	Yes	Alpha-numeric	The application ID issued by the Playblazer platform when the app was created
secret_key	Yes	Alpha-numeric	The secret key issued by the Playblazer platform when the app was created
MODE	Yes	String	The mode for user ID interpretation
USER_ID	Yes	String	The user ID for whom the timer should be created. This user then becomes the owner of the timer.
timeout	Yes	Numeric	The timeout of the timer (used to create a one-shot timer). Can be a float value - like 30.3. Units are in seconds.
period	Yes	Numeric	Same as “timeout” - but used to create a periodic timer. Units are in seconds.
fmt	No	String	One of (json | xml) - the format of output

Either period or timeout should be passed - not both. If both are passed, “period” will override “timeout” and the resulting timer will be a periodic timer.

The output for successful call will contain status=ok and timer ID for the timer created.

Example

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    -F "timeout=100" \
    "http://api.playblazer.com/v1/app/1/timer/fb/kunalg/add"

Output:

{
    "status": "ok",
    "timer_id": "9c6fe5112a3c480b9339a264a78abe91"
}

API: Cancel Timer

Cancel Timer API

URL: {BASE_URL}/app/<APP_ID>/timer/<TIMER_ID>/cancel

Request Method: HTTP POST

Parameter	Mandatory	Type	Description
APP_ID	Yes	Alpha-numeric	The application ID issued by the Playblazer platform when the app was created
secret_key	Yes	Alpha-numeric	The secret key issued by the Playblazer platform when the app was created
TIMER_ID	Yes	String	The timer ID to be cancelled.
fmt	No	String	One of (json | xml) - the format of output

Upon successful execution, the API simply returns status=ok and internally generates an event notification to the owner.

Example

URL Call:

curl -X POST \
    -F "secret_key=cb8d878989b9478e96d1b1574a1bf4ec" \
    "http://api.playblazer.com/v1/app/1/timer/9c6fe5112a3c480b9339a264a78abe91/cancel"

Output:

{
    "status": "ok"
}