Quickstart: Connecting using XML HTTP Request (IXHR2)

Use the IXMLHTTPRequest2 interface to send HTTP GET and POST requests to a web service using C++.The XML HTTP Request 2 GET sample and XML HTTP Request 2 POST sample demonstrate the functionality detailed in this topic.

Note  To make HTTP requests in a Windows Store app developed with C#, see Quickstart: Connecting using HttpClient.

IXMLHTTPRequest2 allows applications to run in a Multi-Threaded Apartment (MTA), a requirement for running under the Windows Runtime in Windows 8. Running in an MTA means that a thread that has access to an IXMLHTTPRequest2 object does not block on request or response processing for other IXMLHTTPRequest2 objects running in the same apartment.

This interface also implements a callback model for event handling. Because IXMLHTTPRequest2 methods allow only asynchronous method calls, to receive completion callbacks an application must pass a pointer to an IXMLHTTPRequest2Callback object when it first calls IXMLHTTPRequest2::Open to create an HTTP request.

Prerequisites

Examples in this topic are provided in C++. A basic understanding of HTTP request patterns as detailed by RFC 2616 is required.

Create and send a GET request

1. First create the references required for this operation as well as the callback that indicates request completion. The XML HTTP Request 2 GET sample defines its own implementations of IXMLHTTPRequest2 and IXMLHTTPRequest2Callback, which are used in the creation of the required operational objects in the following examples.

   C++

   Copy

   
   HRESULT hr = S_OK;
   DWORD dwStatus = 0;
   BOOL fAbort = TRUE;
   ComPtr<IXMLHTTPRequest2> spXHR;
   ComPtr<CXMLHttpRequest2Callback> spXhrCallback;
   
   

2. Create and initialize instances of the IXMLHTTPRequest2 and IXMLHTTPRequest2Callback objects.

   C++

   Copy

   
   
   //
   // Create and initialize an IXMLHTTPRequest2 object
   //
   hr = CoCreateInstance(CLSID_FreeThreadedXMLHTTP60,
                         NULL,
                         CLSCTX_INPROC_SERVER,
                         IID_PPV_ARGS(&spXHR));
   
   //
   //Create and initialize an IXMLHTTPRequest2Callback object
   //
   hr = MakeAndInitialize<CXMLHttpRequest2Callback>(&spXhrCallback);
   
   
   

3. configure the GET request and send it to the server.

   C++

   Copy

   
   
   hr = spXHR->Open(L"GET",              // Method.
                    pcwszUrl,            // Url.
                    spXhrCallback.Get(), // Callback.
                    NULL,                // Username.
                    NULL,                // Password.
                    NULL,                // Proxy username.
                    NULL);               // Proxy password.
   
   //
   //Send the GET request
   //
   hr = spXHR->Send(NULL, 0);
   
   
   

4. Wait for the completion of the request.

   C++

   Copy

   
   hr = spXhrCallback->WaitForComplete(&dwStatus);
   
   
   

   Note  Callers needing to receive completion or status events on a STA or UI thread must use a mechanism that will not block the threads window message pump. One example is by posting a window message to the STA or UI thread window handle.

Create and send a POST request

1. Like the GET example, we first create the references required for this operation as well as the callback that indicates request completion. The XML HTTP Request 2 POST sample also defines its own implementations of IXMLHTTPRequest2 and IXMLHTTPRequest2Callback, which are used in the creation of the required operational objects in the following examples. However, for the POST operation we will need to create the stream used for the operation using XMLHttpRequest2PostStream, an implementation if ISequentialStream defined for the sample. Alternatives to using ISequentialStream for a POST request include SHCreateMemStream/SHCreateStreamOnFile for desktop apps, and CreateStreamOverRandomAccessStream for Windows Store apps.

   First create the references required for this operation as well as the callback that indicates request progress. We've also created and defined variables used to represent the size of the file to be sent and indicate request completion.

   C++

   Copy

   
   HRESULT hr = S_OK;
   DWORD dwStatus = 0;
   ULONGLONG ullFileSize = 0;
   BOOL fAbort = TRUE;
   ComPtr<IXMLHTTPRequest2> spXHR;
   ComPtr<CXMLHttpRequest2Callback> spXhrCallback;
   ComPtr<CXMLHttpRequestPostStream> spXhrPostStream;
   
   

2. Create and initialize objects of the IID_IXMLHTTPRequest2, CXMLHTTPRequest2Callback, and XMLHTTPRequestPostStream classes.

   C++

   Copy

   
   //
   //Initialize IXMLHTTPRequest2Callback
   //
   hr = MakeAndInitialize<CXMLHttpRequest2Callback>(&spXhrCallback);
   if (FAILED(hr))
   {
       goto Exit;
   }
   
   //
   // Create an object of the CXMLHttpRequestPostStream class
   //
   spXhrPostStream = Make<CXMLHttpRequestPostStream>();
   if (spXhrPostStream == NULL)
   {
       hr = E_OUTOFMEMORY;
       goto Exit;
   }
   
   

3. Open the file and get the size.

   C++

   Copy

   
   //
   //Open the file
   //
   hr = spXhrPostStream->Open(pcwszFileName);
   
   //
   //Get file size
   //
   hr = spXhrPostStream->GetSize(&ullFileSize);
   
   
   

4. Prepare the POST request and send it to the server.

   C++

   Copy

   
   //
   //Configure the POST request
   //
   hr = spXHR->Open(L"POST",             // Method.
                    pcwszUrl,            // Url.
                    spXhrCallback.Get(), // Callback.
                    NULL,                // Username.
                    NULL,                // Password.
                    NULL,                // Proxy username.
                    NULL);               // Proxy password.
   if (FAILED(hr))
   {
       goto Exit;
   }
   
   //
   //Send the POST request
   //
   hr = spXHR->Send(spXhrPostStream.Get(), ullFileSize);
   if (FAILED(hr))
   {
       goto Exit;
   }
   
   

5. Wait for the completion of the request.

   C++

   Copy

   
   hr = spXhrCallback->WaitForComplete(&dwStatus);
   if (FAILED(hr))
   {
       goto Exit;
   }
   
   fAbort = FALSE;
   
   

   Note  Callers needing to receive completion or status events on a STA or UI thread must use a mechanism that will not block the threads window message pump. One example is by posting a window message to the STA or UI thread window handle.

Summary

In this topic we reviewed how to initiate a web service connection with GET and POST requests using the IXMLHTTPRequest2 interface.

Related topics

IXMLHTTPRequest2

IXMLHTTPRequest2Callback

Build date: 11/29/2012