{"id":494,"date":"2011-11-11T19:18:29","date_gmt":"2011-11-11T19:18:29","guid":{"rendered":"http:\/\/www.drmop.com\/?p=494"},"modified":"2011-11-12T09:49:00","modified_gmt":"2011-11-12T09:49:00","slug":"marmalade-sdk-tutorial-sending-and-retrieving-data-from-the-web","status":"publish","type":"post","link":"http:\/\/www.drmop.com\/index.php\/2011\/11\/11\/marmalade-sdk-tutorial-sending-and-retrieving-data-from-the-web\/","title":{"rendered":"Marmalade SDK Tutorial – Sending and Retrieving Data From the Web"},"content":{"rendered":"

This tutorial is part of the Marmalade SDK tutorials collection. To see the tutorials index\u00a0click here<\/a><\/p>\n

In our previous tutorial we tidied up the IwGame engine and properly separated our engine calls away from our game code. We ended up with a nice system that allows us to begin building a game. This week we are going on a slight diversion because I have recently been working on sending and retrieving data from the web. I think that its important for any game engine to be able to pull in data from outside itself as it allows us to create games that are easily upgradable without having to put a new version of the game through the app store approval process. Its also cool to be able to send data to the web as it allows us to do cool stuff such as communicating with web services, accessing functionality that could add a lot of value to our games or apps. If you just want the code to this tutorial then you can\u00a0download it from here<\/a>.<\/p>\n

I am actually going to do a couple of tutorials today that cover this subject, the first is covering the basics of interfacing with Marmalade\u2019s IwHttp module that allows us to send GET and POST requests to a web server.<\/p>\n

Oh, the reason for this diversion is because over the last few days I have been working to produce a cross platform ad API that allows Marmalade SDK developers to use Inner-active\u2019s ads on any platform by writing a system that interfaces with Inner-active\u2019s<\/a> ad server and pulling back text and image based ads. Thus far I have the system returning and displaying ads. I just need to write the display system into its own view control and get the click system working. once that\u2019s finished, it will become part of the IwGame game engine. I will blog about that when its finished. If you are interested in beta testing it then please get in touch<\/a>.<\/p>\n

IwHttp \u2013 Marmalade\u2019s API for Performing HTTP Requests<\/h2>\n

IwHttp is the base module used by the Marmalade SDK that allows you to send and receive data from a web server over http and https. IwHttp allows you to perform both GET and POST operations. We have gone one step further however and simplified and extended its usefulness creating a new class called CIwGameHttpManager. If you would like to see how to use the IwHttp class in the manager then take a look at IwGameHttp.cpp and iwGameHttp.h.<\/p>\n

CIwGameHttpManager \u2013 A Queued Http Request Manager<\/h2>\n

CIwGameHttpManager is a singleton class that allows you to throw GET and POST requests to it. The manager will queue the requests and them one by one until no requests are left in the queue. Note that the next request is only sent after the first returns. I\u2019m not going to go into the internals of CIwGameHttpManager because the it and its associated classes constitute a lot of code. I will however explain how to use them.<\/p>\n

Firstly you need to instantiate and initialise the CIwGameHttpManager singleton using:<\/p>\n

\r\n
\r\n\/\/ Initialise the http manager<\/span>\r\nCIwGameHttpManager::Create();\r\nIW_GAME_HTTP_MANAGER->Init();<\/blockquote>\r\n<\/pre>\n
And before you exit your game \/ app clean-up the manager using:<\/p>\n
\r\n
\r\n\/\/ Clean up http manager<\/span>\r\nIW_GAME_HTTP_MANAGER->Release();\r\nCIwGameHttpManager::Destroy();<\/blockquote>\r\n<\/pre>\n
In your main loop, you will also need to call the manager update so that it can do its stuff using:<\/p>\n
\r\n
\r\n\/\/ Update http manager<\/span>\r\nIW_GAME_HTTP_MANAGER->Update();<\/blockquote>\r\n<\/pre>\n
Making a GET Request \u2013 Getting Data From a Server<\/h2>\n
To make a GET request we need to create a persistent instance of CIwGameHttpRequest and set it up, like this:<\/p>\n
\r\n
\r\nCIwGameHttpRequest* Request = new CIwGameHttpRequest();\r\nRequest->setGET();\r\nRequest->setURI(\u201chttp:\/\/www.battleballz.com\/default.aspx\u201d);\r\nRequest->setContentAvailableCallback(&DataRetrievedCallback, (void*)this);\r\nIW_GAME_HTTP_MANAGER->AddRequest(Request);<\/blockquote>\r\n<\/pre>\n
Note that we have set a callback function that will be called when our data is available to use. Here is an example callback:<\/p>\n
\r\n
\r\nint32 DataRetrievedCallback(void* caller, void* data)\r\n{\r\n    CIwGameHttpRequest* request = (CIwGameHttpRequest*)caller;\r\n\r\n    if (request->getProcessed())                                    \/\/ Check to see if our request was processed by the http manager<\/span>\r\n    {\r\n        \/\/ To get to our data we call request->getContent();<\/span>\r\n        \/\/ To get to our data length we call request->getContentLength();<\/span>\r\n        IW_GAME_HTTP_MANAGER->RemoveRequest(request);                \/\/ Remove request from http manager queue<\/span>\r\n    }\r\n\r\n    return 0;\r\n}<\/blockquote>\r\n<\/pre>\n
As you can see its ultra simple to retrieve data from the web.<\/p>\n
Making a POST Request \u2013 Sending Data to a Server<\/h2>\n
To make a POST request we need to create a persistent instance of CIwGameHttpRequest and set it up, like this:<\/p>\n
\r\n
\r\nCIwGameHttpRequest* Request = new CIwGameHttpRequest();;\r\nRequest->setPOST();\r\nRequest->setURI(\u201chttp:\/\/test.battleballz.com\/Test.asmx \u201d);\r\nRequest->setContentAvailableCallback(&DataRetrievedCallback, (void*)this);<\/blockquote>\r\n<\/pre>\n
Note that up to this point the setup is very similar except we specify setPOST() instead of setGET().<\/p>\n
However we want to send some data to the server we have to, so we have to put it somewhere, this is done using the posts body llke this:<\/p>\n
\r\n
\r\nchar length[32];\r\nconst char* body = \"<?xml version=\\\"1.0\\\" encoding=\\\"utf-8\\\"?><soap12:Envelope  xmlns:xsi=\\\"http:\/\/www.w3.org\/2001\/XMLSchema-instance\\\"<\/a> xmlns:xsd=\\\"http:\/\/www.w3.org\/2001\/XMLSchema\\\"<\/a> xmlns:soap12=\\\"http:\/\/www.w3.org\/2003\/05\/soap-envelope\\\"<\/a>><soap12:Body><HelloWorld  xmlns=\\\"http:\/\/www.battleballz.com\/test\\\"<\/a> \/><\/soap12:Body><\/soap12:Envelope>\";\r\nRequest->AddHeader(\"Content-Type\", \"application\/soap+xml; charset=utf-8\");\r\nsprintf(length, \"%d\", strlen(body));\r\nRequest->AddHeader(\"Content-Length\", length);\r\nRequest->setBody(body);<\/blockquote>\r\n<\/pre>\n
Then we add the request to the http manager<\/p>\n
\r\n
\r\nIW_GAME_HTTP_MANAGER->AddRequest(Request);<\/blockquote>\r\n<\/pre>\n
In the above example the body string holds an XML based SOAP request that we are sending to my test ASP.NET web service. In this case when the server gets this SOAP request it will call a method called HelloWorld which returns some data to us.<\/p>\n
Note that when we send data to a web server we need to send some details about that data such as its type and length. In the above example we accomplish this by adding headers to our POST request.<\/p>\n
When the POST has been made the web server will return a response which can be picked up in our callback function.<\/p>\n
Ok, that all looks quite straight forward, but we can make things much simpler if we just want to download files from our web server, in steps the IwGameFile class<\/p>\n
CIwGameFile \u2013 File Class That Handles Loading of Local and External files<\/h2>\n
Yes, we decided to put together a quick file class that handles loading of files from local storage and from an external web server. All you have to do is pass the URL and an optional callback (my kindness knows no bounds!)<\/p>\n
Again, I don\u2019t want to go into the intricate details about the implementation, instead  I am opting for the telling you how to use it approach. IwGame is starting to become a small beast and I would rather spend the time improving it.<\/p>\n
CIwGameFile is a basic general purpose file system class that allows you to open, create, read and write files. In addition it allows you to open a file located somewhere on the web using the http protocol.<\/p>\n
Heres an example on how to open a local file, read some data and close the file:<\/p>\n
\r\n
\r\nCIwGameFile* file = new CIwGameFile();\r\nfile->Open(\"monkey_magic.txt\u201d);\r\nfile->Read(my_buffer, 1024);\r\nfile->Close();<\/blockquote>\r\n<\/pre>\n
And here\u2019s an example showing how to open a read the same file located on the web:<\/p>\n
\r\n
\r\nCIwGameFile* file = new CIwGameFile();\r\nfile->Open(\"http:\/\/www.battleballz.com\/monkey_magic.txt\u201d, false, true);\r\nfile->Read(my_buffer, 1024);\r\nfile->Close();<\/blockquote>\r\n<\/pre>\n
Note that the above method blocks the main loop and does essentially stops all processing of the game until the file is returned. I would instead recommend using a none blocking method like this:<\/p>\n
\r\n
\r\nCIwGameFile* file = new CIwGameFile();\r\nfile->Open(\"http:\/\/www.battleballz.com\/monkey_magic.txt\u201d);\r\nfile->setFileAvailableCallback(FileLoadedCallback);<\/blockquote>\r\n<\/pre>\n
And our callback would look something like this:<\/p>\n
\r\n
\r\nint32 FileLoadedCallback(void* caller, void* data)\r\n{\r\n\tCIwGameFile* file = (CIwGameFile*)caller;\r\n\tfile->Read(my_buffer, 1024);\r\n\tfile->Close();\r\n\r\n\treturn 0;\r\n}<\/blockquote>\r\n<\/pre>\n
IwGameFile still requires a few upgrades to complete its functionality. Here are a few planned updates:<\/p>\n