CloudPlugs Class Reference

Public Member Functions
	CloudPlugs (Client &aClient, const char *host="api.cloudplugs.com")
	~CloudPlugs ()
boolean	setHost (const char *host)
const char *	getHost ()
int	getLastHttpResult ()
CP_ERR_CODE	getLastErrCode ()
boolean	setAuth (const char *id, const char *pass, boolean is_master)
boolean	getAuthId (String &id)
boolean	getAuthPass (String &password)
boolean	isAuthMaster ()
boolean	enrollProduct (const char *body, String &result)
boolean	enrollPrototype (const char *body, String &result)
boolean	enrollCtrl (const char *body, String &result)
boolean	controlDevice (const char *body, String &result)
boolean	uncontrolDevice (const char *plugid, const char *plugid_controlled, String &result)
boolean	getDevice (const char *plugid, String &result)
boolean	getDeviceProp (const char *plugid, const char *prop, String &result)
boolean	setDeviceProp (const char *plugid, const char *prop, const char *value, String &result)
boolean	removeDeviceProp (const char *plugid, const char *prop, String &result)
boolean	setDevice (const char *plugid, const char *value, String &result)
boolean	unenroll (const char *plugid, String &result)
boolean	getChannel (const char *channel_mask, const char *query, String &result)
boolean	retrieveData (const char *channel_mask, const char *query, String &result)
boolean	publishData (const char *channel, const char *body, String &result)
boolean	removeData (const char *channel_mask, const char *body, String &result)
boolean	setDeviceLocation (const char *plugid, const char *value, String &result)
boolean	getDeviceLocation (const char *plugid, String &result)

Protected Attributes
Client &	client
HttpClient *	httpClient
String	host
String	id
String	auth
boolean	is_master
int	http_res
CP_ERR_CODE	err

Constructor & Destructor Documentation

CloudPlugs()

CloudPlugs	(	Client &	aClient,
		const char *	host = "api.cloudplugs.com"
	)

~CloudPlugs()

~CloudPlugs

(

)

Member Function Documentation

controlDevice()

boolean controlDevice	(	const char *	body,
		String &	result
	)

Request for controlling a device and place the response in *result and *result_length.

Parameters

body	A buffer containing a json object like this: { "model" : PLUG_ID, // model id of the device to control "ctrl" : HWID, // serial number (hwid) of the device to control "pass" : String, }
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

enrollCtrl()

boolean enrollCtrl	(	const char *	body,
		String &	result
	)

Request for enrolling a new or already existent controller device and place the response in *result and *result_length.

Parameters

body	A buffer containing a json object like this: { "model" : PLUG_ID, // model id of the device to control "ctrl" : HWID, // serial number (hwid) of the device to control "pass" : String, "hwid" : HWID, // unique string to identify this controller device "name" : String // the name of this device }
result	If not NULL, then / A pointer such that - *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

enrollProduct()

boolean enrollProduct	(	const char *	body,
		String &	result
	)

Request for enrolling a new production device and place the response in *result and *result_length.

Parameters

body	A buffer containing a json object like this: { "model" : PLUG_ID, // the model of this device "hwid" : HWID, // the serial number "pass" : String, "props" : JSON // optional, to initialize the custom properties }
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

enrollPrototype()

boolean enrollPrototype	(	const char *	body,
		String &	result
	)

Request for enrolling a prototype and place the response in *result and *result_length.

Parameters

body	A buffer containing a json object like this: { "hwid" : HWID, // optional, if absent it will be set as a random unique string "pass" : String, // optional, if absent set as the X-Plug-Master of the company "name" : String, "perm" : PERM_FILTER, // optional, if absent permit all "props" : JSON // optional, to initialize the custom properties }
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

getAuthId()

boolean getAuthId

(

String &

id

)

Get the authentication id (PLUG_ID or email) of the session.

Parameters

id	The destination String where the authentication id will be written.

Returns

true if the buffer was correctly written, false otherwise.

getAuthPass()

boolean getAuthPass

(

String &

password

)

Get the authentication password of the session.

Parameters

password

The destination String where the authentication password will be written.

Returns

true if the buffer was correctly written, false otherwise.

getChannel()

boolean getChannel	(	const char *	channel_mask,
		const char *	query,
		String &	result
	)

Request for retrieving list channels/channels about already published data and place the response in *result and *result_length.

Parameters

channel_mask	The CHMASK
query	If not NULL, must be a url-encode string containing those values: before: Optional, TIMESTAMP or OBJECT_ID timestamp valid if greater than zero after: Optional, TIMESTAMP or OBJECT_ID timestamp valid if greater than zero at: Optional, TIMESTAMP_CSV timestamp valid if greater than zero of: Optional, PLUG_ID_CSV offset: Optional Number: positive integer (including 0) limit: Optional Number: positive integer (including 0)
result	A pointer such that *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

CP_SUCCESS if the request succeeds, CP_FAILED otherwise.

getDevice()

boolean getDevice	(	const char *	plugid,
		String &	result
	)

Request for reading a device and place the response in *result and *result_length.

Parameters

plugid	The PLUG_ID of the device.
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

getDeviceLocation()

boolean getDeviceLocation	(	const char *	plugid,
		String &	result
	)

Request for writing or deleting device location and place the response in *result and *result_length.

Parameters

plugid	If not NULL, then the PLUG_ID of the device, otherwise the device referenced in the session.
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

getDeviceProp()

boolean getDeviceProp	(	const char *	plugid,
		const char *	prop,
		String &	result
	)

Request for reading the device properties and place the response in *result and *result_length.

Parameters

plugid	The PLUG_ID of the device.
prop	If NULL, then all properties value; otherwise the single property value.
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

getHost()

const char* getHost

(

)

Get the current base url.

Returns

The base url.

getLastErrCode()

CP_ERR_CODE getLastErrCode

(

)

Return a human-readable string that describes the last error.

Returns

A human-readable string that describes the last error.

getLastHttpResult()

int getLastHttpResult

(

)

Return a human-readable string that describes the last error.

Returns

A human-readable string that describes the last error.

isAuthMaster()

boolean isAuthMaster

(

)

Return the authentication mode in the session.

Returns

true if using master authentication in the session; false if using regular authentication.

publishData()

boolean publishData	(	const char *	channel,
		const char *	body,
		String &	result
	)

Request for publishing data and [optionally] place the response in *result and *result_length.

Parameters

channel	A optional CHANNEL , if NULL data need to contain a couple "channel":"channel"
body	A json object or an array of objects like this: { "id" : “PLUG_ID”, "channel" : CHANNEL, // optional, to override the channel in the url "data": JSON, "at" : TIMESTAMP, "of" : PLUG_ID, // optional, check if the X-Plug-Id is authorized for setting this field "is_priv" : Boolean, // optional, default false "expire_at" : TIMESTAMP, // optional, expire date of this data entry "ttl" : Number // optional, how many seconds this data entry will live (if "expire_at" is present, then this field is ignored) }
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

removeData()

boolean removeData	(	const char *	channel_mask,
		const char *	body,
		String &	result
	)

Request for deleting already published data and [optionally] place the response in *result and *result_length.

Parameters

channel_mask	The CHMASK
body	A buffer containing a json object like this (at least one param is required: id, before, after or at): { "id" : OBJECT_ID_CSV , "before" : TIMESTAMP or PLUG_ID, "after" : TIMESTAMP or PLUG_ID, "at" : TIMESTAMP_CSV , "of" : PLUG_ID_CSV }
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

removeDeviceProp()

boolean removeDeviceProp	(	const char *	plugid,
		const char *	prop,
		String &	result
	)

Request for deleting device property and [optionally] place the response in *result and *result_length.

Parameters

plugid	The PLUG_ID of the device.
prop	The single property value to be remove.
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

retrieveData()

boolean retrieveData	(	const char *	channel_mask,
		const char *	query,
		String &	result
	)

Request for retrieving already published data and place the response in *result and *result_length.

Parameters

channel_mask	The CHMASK
query	If not NULL, must be a url-encode string containing those values: before: Optional, TIMESTAMP or OBJECT_ID timestamp valid if greater than zero after: Optional, TIMESTAMP or OBJECT_ID timestamp valid if greater than zero at: Optional, TIMESTAMP_CSV timestamp valid if greater than zero of: Optional,PLUG_ID_CSV offset: Optional Number: positive integer (including 0) limit: Optional Number: positive integer (including 0)
result	A pointer such that *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

setAuth()

boolean setAuth	(	const char *	id,
		const char *	pass,
		boolean	is_master
	)

Set the session authentication credentials.

Parameters

id	A string containing the PLUG_ID or the master email.
pass	A string containing the authentication code.
is_master	true for using master authentication in the session; false for using regular authentication.

Returns

true if the authentication is set correctly, false otherwise.

setDevice()

boolean setDevice	(	const char *	plugid,
		const char *	value,
		String &	result
	)

Request for modifying device and [optionally] place the response in *result and *result_length.

Parameters

plugid	The PLUG_ID of the device.
value	A json object like this: { "perm" : PERM_FILTER, // optional, it contains just the sharing filters to modify "name" : String, // optional "status" : STATUS, // optional "props" : Object // optional, it contains just the properties to modify }
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

setDeviceLocation()

boolean setDeviceLocation	(	const char *	plugid,
		const char *	value,
		String &	result
	)

Request for writing or deleting device location and [optionally] place the response in *result and *result_length.

Parameters

plugid	If not NULL, then the plug-id of the device, otherwise the device referenced in the session.
value	A json object like this: { "x" : LONGITUDE "y" : LATITUDE "z" : ALTITUDE //optional "r" : ACCURACY //optional "t" : TIMESTAMP } Use null to delete a location property.
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

setDeviceProp()

boolean setDeviceProp	(	const char *	plugid,
		const char *	prop,
		const char *	value,
		String &	result
	)

Request for writing or deleting device properties and [optionally] place the response in *result and *result_length.

Parameters

plugid	The PLUG_ID of the device.
prop	If NULL, then value must be an object; otherwise the single property value is written.
value	A json value, use null to delete one or all device properties.
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

setHost()

boolean setHost

(

const char *

host

)

Change the default base url.

Parameters

host	http or https url string.

Returns

true if the new base url is set correctly, false otherwise.

uncontrolDevice()

boolean uncontrolDevice	(	const char *	plugid,
		const char *	plugid_controlled,
		String &	result
	)

Request for uncontrol a device and [optionally] place the response in *result and *result_length.

Parameters

plugid	If NULL, then is the PLUG_ID in the session.
plugid_controlled	If not NULL, then the device(s) to uncontroll (default all associated devices).
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

unenroll()

boolean unenroll	(	const char *	plugid,
		String &	result
	)

Request for removing any device (development, product or controller) and [optionally] place the response in *result and *result_length.

Parameters

plugid	The PLUG_ID_CSV of the device(s) to remove; if NULL then remove the device referenced in the session.
result	If not NULL, then *result will contain the dynamically allocated json string of the retrieved response body. The caller is responsible to free memory in *result.

Returns

true if the request succeeds, false otherwise.

Member Data Documentation

auth

String auth

protected

client

Client& client

protected

err

CP_ERR_CODE err

protected

host

String host

protected

http_res

int http_res

protected

httpClient

HttpClient* httpClient

protected

id

String id

protected

is_master

boolean is_master

protected