The embedded API header. More...

Macros
#define	__PARSE_H__

#define	APPLICATION_ID_MAX_LEN 40
	The length of application id.

#define	CLIENT_KEY_MAX_LEN 40
	The length of client key.

#define	OBJECT_ID_MAX_LEN 16
	The length of object id.

#define	INSTALLATION_ID_MAX_LEN 36
	The length of installation id.

#define	SESSION_TOKEN_MAX_LEN 40
	The length of session token.

Typedefs
typedef const struct ParseClientInternal *	ParseClient
	Parse client handle. More...

typedef void(*	parseRequestCallback) (ParseClient client, int error, int httpStatus, const char *httpResponseBody)
	Callback for API requests. More...

typedef void(*	parsePushCallback) (ParseClient client, int error, const char *data)
	Callback for push notifications and errors from the push service. More...

Functions
ParseClient	parseInitialize (const char applicationId, const char clientKey)
	Initialize the Parse client and user session. More...

void	parseSetInstallationId (ParseClient client, const char *installationId)
	Set the installation object id for this client. More...

const char *	parseGetInstallationId (ParseClient client)
	Return the client installation id. More...

void	parseSetSessionToken (ParseClient client, const char *sessionToken)
	Set the session token for the Parse client. More...

void	parseClearSessionToken (ParseClient client)
	Clear the session token. More...

const char *	parseGetSessionToken (ParseClient client)
	Return the client session token. More...

void	parseSetPushCallback (ParseClient client, parsePushCallback callback)
	Set the callback for push notifications and errors. More...

int	parseStartPushService (ParseClient client)
	Start the push notifications service. More...

void	parseStopPushService (ParseClient client)
	Stop the push notifications service. More...

int	parseProcessNextPushNotification (ParseClient client)
	Process next pending push notification. More...

int	parseGetPushSocket (ParseClient client)
	Request Parse push file handle for use with select call. More...

void	parseRunPushLoop (ParseClient client)
	Process push notifications events in a loop. More...

void	parseSendRequest (ParseClient client, const char httpVerb, const char httpPath, const char *httpRequestBody, parseRequestCallback callback)
	Send an API request. More...

int	parseGetErrorCode (const char *httpResponseBody)
	Extract Parse error code. More...

Detailed Description

The embedded API header.

Typedef Documentation

ParseClient

Parse client handle.

This handle is used with all SDK methods to associate the specific client (installation, and optionally user) with the API calls.

A client has to be initialized using parseInitialize() which will associate it with a specific Parse application and the key to use when making requests.

Each client has an associated installation id that represents the device, and an optional session token that represents the user to the Parse backend. Both installation id and session token can be explicitly set for the client. If an installation id is not explicitly set, the SDK will generate a new one the first time it need it. If a session token is not set, the SDK will NOT generate one and will work in unauthenticated mode.

parsePushCallback

Callback for push notifications and errors from the push service.

Parameters

[in]	client	The Parse client associated with the callback.
[in]	error	OS-specific error code. If the push service received the notification data normally, this will be 0. If any error occurred during receiving the notification data, the rest of the parameters are meaningless.
[in]	data	The data for the incoming push notification. If the notification is received successfully, this is a JSON document describing the payload for the notification.

The SDK retains ownership of the notification data buffer. If you need to retain any data from it for use outside of the scope of the callback, make a copy.

parseRequestCallback

Callback for API requests.

Called when an API request is finished.

Parameters

[in]	client	The Parse client that made the API request.
[in]	error	OS-specific error code. If the API request was successful, this will be 0. If any error occured during the request, the rest of the parameters are meaningless.
[in]	httpStatus	HTTP status of the API request.
[in]	httpResponseBody	The response body for the request. If the request is successful, this is a JSON document describing the result. If the request is unsuccessful, this contains error details.

The SDK retains ownership of the response body. If you need to retain any data from it for use outside of the scope of the callback, make a copy.

Function Documentation

void parseClearSessionToken ( ParseClient client )

Clear the session token.

Same as parseSetSessionToken(client, NULL);

int parseGetErrorCode ( const char * httpResponseBody )

Extract Parse error code.

Helper function to extract Parse errors from the response body, when httpStatus of the response is 4xx or 5xx. TODO: Link to the public documentation of the Parse error codes

Parameters

[in] httpResponseBody The response body for the request.

Returns: Return the error code from the server.

The caller retains ownership of the httpResponseBody buffer, and is responsible for freeing it and reclaiming the memory after this call.

const char * parseGetInstallationId ( ParseClient client )

Return the client installation id.

Return the installation id for the client. If called before the installation id for the client was set, this method will NOT create a new installation object. The typical usage scenario is:

Call parseInitialize().
Call parseGetInstallationId(). 3.a. If the result is not NULL, the SDK has a previous installation id, there's nothing else to do. Otherwise: 3.b.1. If the device has already an installation id, call parseSetInstallationId(). 3.b.2. If the device doesn't have an installation id, the SDK will generate one the first time it needs it.

Parameters

[in] client The Parse client for which the installation id should be returned.

Returns: The instalaltion id.

The SDK retains ownership of the result buffer, and still owns it after this call. Do not free it.

int parseGetPushSocket ( ParseClient client )

Request Parse push file handle for use with select call.

You may want to wait on several system events. This returns the file descriptor used for push so that you can use a 'select' call to wait on multiple descriptors.

Example of using this handle on posix systems with select while implementing a custom event loop:

 int socket = parseGetPushSocket(client);
 while(1) {
   struct timeval tv;
   fd_set receive, send, error;
 
   ...
 
   FD_SET(socket, &error);
   FD_SET(socket, &receive);
 
   // Add other file handles with FD_SET
   // that you are interrested in
 
   select(socket + 1, &receive, &send, &error, &tv);
   parseProcessNextPushNotification(client);
 }

Parameters

[in] client The Parse client for which the push has been started

const char * parseGetSessionToken ( ParseClient client )

Return the client session token.

Return the session token for the client, or NULL if there isn't one.

Parameters

[in] client The Parse client for which the session token should be returned.

Returns: The session token.

The SDK retains ownership of the result buffer, and still owns it after this call. Do not free it.

ParseClient parseInitialize	(	const char *	applicationId,
		const char *	clientKey
	)

Initialize the Parse client and user session.

This method only initializes the Parse client, used for subsequent API requests. It does not start the push service, and does not create or load the installation object for the client.

Parameters

[in]	applicationId	The application id for the Parse application. (required)
[in]	clientKey	The client API key for the Parse application. (required)

Returns: The client handle to use with the SDK.

The caller retains ownership of the applicationId and clientKey buffers, and is responsible for freeing them and reclaiming the memory after this call. The SDK will make copies of the buffers.

int parseProcessNextPushNotification ( ParseClient client )

Process next pending push notification.

Push notifications are processed one at a time. This method will process the next push notification and will call the client callback, if one is set.

Parameters

[in] client The Parse client for which the next event should be processed.

Returns: 0 if there are no more pending notification events or the push service is not started. Positive number if there are more pending notification events.

If the push notifications callback has been set for the client, it will also be called in the case of an error during the processing of the notification. If the callback is not set, the client will not get notified about any errors that during the processing of the notification.

void parseRunPushLoop ( ParseClient client )

Process push notifications events in a loop.

This method will keep processing the push notification events for the client and will call the client callback for each one. If the push notification service for the client is not started or is stopped, this method will exit.

Parameters

[in] client The Parse client for which the push events should be processed.

void parseSendRequest	(	ParseClient	client,
		const char *	httpVerb,
		const char *	httpPath,
		const char *	httpRequestBody,
		parseRequestCallback	callback
	)

Send an API request.

This method makes an API request for the client. If called before installation id for the client is set, this will also create a new installation object.

The API requests supported are any valid reuests that can be made through the REST API as well.

Parameters

[in]	client	The Parse client for which the request is made.
[in]	httpVerb	The type of request - POST, GET, PUT, DELETE
[in]	httpPath	The path for the request, i.e. /1/classes/MyClass
[in]	httpRequestBody	The JSON payload for the request
[in]	callback	The callback to process the result of the request.

The caller retains ownership of the httpVerb, httpPath, and requestBody buffers, and is responsible for freeing them and reclaiming the memory after this call.

void parseSetInstallationId	(	ParseClient	client,
		const char *	installationId
	)

Set the installation object id for this client.

Set the installation object id for this client. If this is not called before making an API request or starting push service, the SDK will create a new installation object for the client.

Parameters

[in]	client	The Parse client for which the installation id will be set.
[in]	installationId	The installation id to be used by the client.

The caller retains ownership of the installationId buffer, and is responsible for freeing it and reclaiming the memory after this call. The SDK will make copies of the buffer.

void parseSetPushCallback	(	ParseClient	client,
		parsePushCallback	callback
	)

Set the callback for push notifications and errors.

This method sets or clears the callback for push notifications and errors from the push service, associated with this client.

This method DOES NOT start or stop the push service.

Parameters

[in]	client	The Parse client for which the callback is set.
[in]	callback	The new callback method. All subsequent push notifications or errors will result in a call to this callback method. If this parameter is NULL, the callback will be removed.

Any push notifications received while there is no callback associated with the client will be skipped, and the application will not received them.

void parseSetSessionToken	(	ParseClient	client,
		const char *	sessionToken
	)

Set the session token for the Parse client.

Parameters

[in]	client	The Parse client for which the session token is set.
[in]	sessionToken	The new session token. All subsequent API calls will use this token for authentication and authorization. If this is NULL, the client will be unauthenticated.

The caller retains ownership of the sessionToken buffer, and is responsible for freeing it and reclaiming the memory after this call. The SDK will make copies of the buffer.

int parseStartPushService ( ParseClient client )

Start the push notifications service.

This method will start the push notification service and will listen for incoming push notifications. If the push service is already started, this will do nothing. To actually process incoming push notifications, it is still necessary to repeatedly call parseProcessNextPushNotification() or call parseRunPushLoop().

Parameters

[in] client The Parse client for which the service should be started.

Returns: OS-specific error if the push can't be started or 0 if started successfully.

If a push callback has been set for the client, any errors during starting the service will passed to it as well.

void parseStopPushService ( ParseClient client )

Stop the push notifications service.

This method will stop the push notification service. If the push service is not started, this will do nothing.

Parameters

[in] client The Parse client for which the service should be stopped.

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation