App42 Cloud API

Windows Phone Cloud SDK

Message

Message API consists of Message and Queue.

Message - Service for sending, pulling and removing Message from a particular queue. Asynchronous messages can be sent to a queue which can be pulled using various receive messages.

Queue - Manages Asynchronous queues. Allows to Create, Delete, Purge messages, View Pending messages and Get all messages.

In order to use the various functions available under a particular API, a developer will have to create an instance of ServiceAPI by passing the apiKey and the secretKey which has been received while creating an app.

ServiceAPI api = new ServiceAPI("<API_KEY>","<SECRET_KEY>");

After initialization, developer needs to call the BuildXXXService method on ServiceAPI instance to get the instance of the particular API that you wish to build. For example, To build an instance of QueueService, BuildQueueService() method needs to be called.

QueueService queueService = api.BuildQueueService()

Once the API instance has been retrieved, You are ready to use the functions available for that particular API.

The Windows Phone API's work in an asynchronous mode that means the response will not be available immediately and all the API methods would not return any value and have return type as void. The response will be returned in callback methods which the caller will provide to the calling method.
As mentioned above that the response will be returned in callback methods, every API method is taking instance of App42Callback (as the last parameter) which will have the implementation of 2 methods: OnSuccess & OnException.(as shown below)

public class CallBack : App42Callback
{
public override void OnSuccess(Object obj)
{
Queue queue = (Queue) obj;
//Do whatever you want with the user object
}
public override void OnException(App42Exception e)
{
//Do whatever you want with the exception
}
}

The callback methods will return the response in the form of Object which will have to be type cast to the object domain object (e.g. App42Response / Queue in this case) The Domain object have the accessor / mutator to access the available properties for that object. You can get the response in the form of JSON as well. We have provided the JSON response with every function detail which can be retrieved by calling the ToString() on the returned object.

public override void OnSuccess(Object obj)
{
Queue queue = (Queue) obj; 
Console.WriteLine("queueName is" + queue.GetQueueName()); 
Console.WriteLine("queueDescription is" + queue.GetQueueDescription()); 
String jsonResponse = queue.ToString(); /* returns the response in JSON format. */ 
}

The functions available under Message API can throw some exceptions in abnormal conditions. Example of the same has been given below.

E.g. If App developer is sending a message on the queue which has not been created, the function will throw the App42Exception (as shown below) with message as "Not Found" and the appErrorCode as "2400" and the details as "Queue with the name '<queueName>' not found.".

public override void OnException(App42Exception ex)
{
int appErrorCode = ex.GetAppErrorCode();
int httpErrorCode = ex.GetHttpErrorCode();
String jsonText = ex.GetMessage(); /* returns the Exception text in JSON format. (as shown below)*/	
}
{
"app42Fault": 
{
"httpErrorCode": 404,
"appErrorCode": 2400,
"message": "Not Found",
"details": "Queue with the name 'MyQueue' not found"
}
}

Below are the HTTP Error Codes and their description, the function under the Message/Queue API can throw.

							
/*
1400 - BAD REQUEST - The Request parameters are invalid
1401 - UNAUTHORIZED - Client is not authorized
1500 - INTERNAL SERVER ERROR - Internal Server Error. Please try again	
*/						

Below are the Application Error Codes and their description, the function under the Message/Queue API can throw.

/*
2400 - NOT FOUND - Queue with the name '<queueName>' not found.
2401 - NOT FOUND - Queue with the name '<queueName>' does not have any messages.
2402 - NOT FOUND -  Queue with the name '<queueName>' and correlationId '<correlationId>' does not have any messages.
2403 - BAD REQUEST - Queue by the name '<queueName>' already exists.
2404 - BAD REQUEST - The request parameters are invalid. This action is only applicable for PULL type queue.
2405 - NOT FOUND - Queue with the name '<queueName>' does not have any pending messages.
*/	
							

Various functions available under Message/Queue API has been explained below.

public void ReceiveMessage(String queueName, Double receiveTimeOut, App42Callback requestCallback)

Pull all the message from the queue.

Parameters:

queueName - The name of the queue from which messages have to be pulled
receiveTimeOut - Receive time out
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Queue object containing messages which have been pulled

Response: Queue Object

Exception:

This method throws following exception.
/*
2400 - NOT FOUND - Queue with the name '<queueName>' not found.
2401 - NOT FOUND - Queue with the name '<queueName>' does not have any messages.
*/		          
For more details click Exception
String queueName ="MyQueue";
long receiveTimeOut = 10000;
	
queueService.ReceiveMessage(queueName, receiveTimeOut,requestCallback);  /* returns the Queue object. */ 
OnSuccess(Object obj){
Queue queue = (Queue) obj;
String queueName =  queue.GetQueueName();  
String queueType =  queue.GetQueueType(); 
IList<Queue.Message> messageList = queue.GetMessageList();
for (int i = 0; i <messageList.Count; i++)
{
Console.WriteLine("correlationId is " + messageList[i].GetCorrelationId());
Console.WriteLine("messageId is " + messageList[i].GetMessageId());
Console.WriteLine("payLoad is " + messageList[i].GetPayLoad());               
} 
String jsonResponse = queue.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "queueName": "MyQueue",
                    "queueType": "PULL",
                    "messages": {
                        "message": {
                            "correlationId": "App42_d929f477-3517-4131-a46d-c2826b701f8d",
                            "payLoad": "Message Description",
                            "messageId": "ID:SHEPHERTZ-59712-1336725186689-0:30:24:1:1"
                        }
                    }
                }
            }
        }
    }
}
public void ReceiveMessageByCorrelationId(String queueName, Double receiveTimeOut, String correlationId, App42Callback requestCallback)

Pull message based on the correlation id.

Parameters:

queueName - The name of the queue from which the message has to be pulled
receiveTimeOut - Receive time out
correlationId - Correlation Id for which message has to be pulled
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Queue containing message which has pulled based on the correlation id

Response: Queue Object

Exception:

This method throws following exception.
/*
2400 - NOT FOUND - Queue with the name '<queueName>' not found.
2402 - NOT FOUND -  Queue with the name '<queueName>' and correlationId '<correlationId>' does not have any messages.
*/ 		          
For more details click Exception
String queueName = "MyQueue";
long receiveTimeOut = 10000;
String correlationId = "App42_d929f477-3517-4131-a46d-c2826b701f8d";

queueService.ReceiveMessageByCorrelationId(queueName, receiveTimeOut, correlationId,requestCallback);  /* returns the Queue object. */ 
OnSuccess(Object obj){
Queue queue = (Queue) obj;
String queueName =  queue.GetQueueName();  
String queueType =  queue.GetQueueType(); 
IList<Queue.Message> messageList = queue.GetMessageList();
for (int i = 0; i <messageList.Count; i++)
{
Console.WriteLine("correlationId is " + messageList[i].GetCorrelationId());
Console.WriteLine("messageId is " + messageList[i].GetMessageId());
Console.WriteLine("payLoad is " + messageList[i].GetPayLoad());  
}	
String jsonResponse = queue.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "queueName": "MyQueue",
                    "queueType": "PULL",
                    "messages": {
                        "message": {
                            "correlationId": "App42_d929f477-3517-4131-a46d-c2826b701f8d",
                            "payLoad": "Description of Messages",
                            "messageId": "ID:SHEPHERTZ-59712-1336725186689-0:30:24:1:1"
                        }
                    }
                }
            }
        }
    }
}
public void RemoveMessage(String queueName, String messageId, App42Callback requestCallback)

Remove message from the queue based on the message id.
Note: Once the message is removed it cannot be pulled.

Parameters:

queueName - The name of the queue from which the message has to be removed
messageId - The message id of the message which has to be removed
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response if removed successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
2400 - NOT FOUND - Queue with the name '<queueName>' not found. 
*/ 		         
For more details click Exception
String queueName = "MyQueue";
String messageId = "ID:SHEPHERTZ-59712-1336725186689-0:30:24:1:1";

queueService.RemoveMessage(queueName, messageId,requestCallback); /* returns the App42Response object. */
OnSuccess(Object obj){
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "messages": {
                        "message": {
                            "queueName": "MyQueue",
                            "messageId": "ID:SHEPHERTZ-59712-1336725186689-0:30:24:1:1"
                        }
                    }
                }
            }
        }
    }
}
public void SendMessage(String queueName, String msg, Double exp, App42Callback requestCallback)

Send message on the queue with an expiry. The message will expire if it is not pulled/dequeued before the expiry.

Parameters:

queueName - The name of the queue to which he message has to be sent
msg - Message that has to be sent
exp - Message expiry time
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Queue object containing message which has been sent with its message id and correlation id

Response: Queue Object

Exception:

This method throws following exception.
/*
2400 - NOT FOUND - Queue with the name '<queueName>' not found.
*/ 		  
For more details click Exception
String queueName = "MyQueue";
String msg = "Its a Real Message";
long exp = 100000;

queueService.SendMessage(queueName, msg, exp,requestCallback);  /* returns the Queue object. */ 
OnSuccess(Object obj){
Queue queue = (Queue) obj;
String queueName =  queue.GetQueueName();  
String queueType =  queue.GetQueueType(); 
IList<Queue.Message> messageList = queue.GetMessageList();
for (int i = 0; i <messageList.Count; i++)
{
Console.WriteLine("correlationId is " + messageList[i].GetCorrelationId());
Console.WriteLine("messageId is " + messageList[i].GetMessageId());
Console.WriteLine("payLoad is " + messageList[i].GetPayLoad());                
}
String jsonResponse = queue.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "queueName": "MyQueue",
                    "queueType": "PULL",
                    "messages": {
                        "message": {
                            "correlationId": "App42_d929f477-3517-4131-a46d-c2826b701f8d",
                            "payLoad": "Its a Real Message"
                        }
                    }
                }
            }
        }
    }
}
public void CreatePullQueue(String queueName, String queueDescription, App42Callback requestCallback)

Creates a type Pull Queue.

Parameters:

queueName - The name of the queue which has to be created
queueDescription - The description of the queue
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Queue object containing queue name which has been created

Response: Queue Object

Exception:

This method throws following exception.
/*
2403 - BAD REQUEST - Queue by the name '<queueName>' already exists.
*/ 		        
For more details click Exception
String queueName =  "MyQueue";
String queueDescription = "Hi its testing Time";

queueService.CreatePullQueue(queueName, queueDescription,requestCallback);  /* returns the Queue object. */ 
OnSuccess(Object obj)
{
Queue queue = (Queue) obj;
Console.WriteLine("correlationId is " + queue.GetQueueName());
Console.WriteLine("description is " + queue.GetDescription(); );  
String jsonResponse = queue.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "queueName": "MyQueue",
                    "queueType": "pull",
                    "description": "Hi its testing Time"
                }
            }
        }
    }
}
public void DeletePullQueue(String queueName, App42Callback requestCallback)

Deletes the Pull type Queue.

Parameters:

queueName - The name of the queue which has to be deleted
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response if deleted successfully

Response: App42Response Object

Exception:

This method throws following exception.
/*
2400 - NOT FOUND - Queue with the name '<queueName>' not found.
*/ 		 
For more details click Exception
String queueName = "MyQueue";
queueService.DeletePullQueue(queueName,requestCallback); /* returns the App42Response object. */
OnSuccess(Object obj)
{
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
                            
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "queueName": "MyQueue",
                    "queueType": "pull",
                    "description": "Queue Description"
                }
            }
        }
    }
}
public void GetMessages(String queueName, Double receiveTimeOut, App42Callback requestCallback)

Messages are retrieved and dequeued from the Queue.

Parameters:

queueName - The name of the queue which have to be retrieved
receiveTimeOut - Receive timeout
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Queue object containing messages in the Queue

Response: Queue Object

Exception:

This method throws following exception.
/*
2400 - NOT FOUND - Queue with the name '<queueName>' not found.
*/ 		        
For more details click Exception
String queueName = "MyQueue";
long receiveTimeOut = 10000;

queueService.GetMessages(queueName, receiveTimeOut,requestCallback);  /* returns the Queue object. */ 
OnSuccess(Object obj){
Queue queue = (Queue) obj;
String queueName =  queue.GetQueueName();  
String queueType =  queue.GetQueueType(); 
IList<Queue.Message> messageList = queue.GetMessageList();
for (int i = 0; i <messageList.Count; i++)
{
Console.WriteLine("correlationId is " + messageList[i].GetCorrelationId());
Console.WriteLine("messageId is " + messageList[i].GetMessageId());
Console.WriteLine("payLoad is " + messageList[i].GetPayLoad());                
}
String jsonResponse = queue.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "queueName": "MyQueue",
                    "queueType": "PULL",
                    "messages": {
                        "message": {
                            "correlationId": "App42_d929f477-3517-4131-a46d-c2826b701f8d",
                            "payLoad": "Hi its Queue Description",
                            "messageId": "ID:SHEPHERTZ-59712-1336725186689-0:30:24:1:1"
                        }
                    }
                }
            }
        }
    }
}
public void PendingMessages(String queueName, App42Callback requestCallback)

Messages which are pending to be dequeue.
Note: Calling this method does not dequeue the messages in the Queue. The messages stay in the Queue till they are dequeued

Parameters:

queueName - The name of the queue from which pending messages have to be fetched
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

Queue object containing pending messages in the Queue

Response: Queue Object

Exception:

This method throws following exception.
/*
2400 - NOT FOUND - Queue with the name '<queueName>' not found. 
2405 - NOT FOUND - Queue with the name '<queueName>' does not have any pending messages.
*/ 		  
For more details click Exception
String queueName = "MyQueue";
queueService.PendingMessages(queueName,requestCallback);  /* returns the Queue object. */ 
OnSuccess(Object obj){
Queue queue = (Queue) obj;
String queueName =  queue.GetQueueName();  
String queueType =  queue.GetQueueType(); 
IList<Queue.Message> messageList = queue.GetMessageList();
for (int i = 0; i <messageList.Count; i++)
{
Console.WriteLine("correlationId is " + messageList[i].GetCorrelationId());
Console.WriteLine("messageId is " + messageList[i].GetMessageId());
Console.WriteLine("payLoad is " + messageList[i].GetPayLoad());                
} 
String jsonResponse = queue.ToString(); /* returns the response in JSON format. (as shown below)*/
} 
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "queueName": "MyQueue",
                    "queueType": "PULL",
                    "messages": {
                        "message": {
                            "correlationId": "App42_d929f477-3517-4131-a46d-c2826b701f8d",
                            "payLoad": "DESCRIPTION",
                            "messageId": "ID:SHEPHERTZ-59712-1336725186689-0:30:24:1:1"
                        }
                    }
                }
            }
        }
    }
}
public void PurgePullQueue(String queueName, App42Callback requestCallback)

Purges message on the Queue.
Note: once the Queue is purged the messages are removed from the Queue and wont be available for dequeueing.

Parameters:

queueName - The name of the queue which has to be purged
requestCallback - Callback instance that will have the implementation of OnSuccess & OnException of App42Callback.

Returns:

App42Response object

Response: App42Response Object

For more details click Exception
String queueName = "MyQueue";
queueService.PurgePullQueue(queueName,requestCallback);  /* returns the Queue object. */ 
OnSuccess(Object obj)
{
App42Response response = (App42Response) obj;
Boolean success = response.IsResponseSuccess();
String jsonResponse = response.ToString(); /* returns the response in JSON format. (as shown below)*/
}
{
    "app42": {
        "response": {
            "success": true,
            "queues": {
                "queue": {
                    "queueName": "MyQueue",
                    "queueType": null,
                    "description": "Queue Description"
                }
            }
        }
    }
}