blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Public Member Functions | Protected Attributes | Properties

GDHttpRequest Class Reference

Standards-based HTTP request, also supporting HTTPS and communication across the firewall (deprecated). More...

#import <GDNETiOS.h>

List of all members.

Public Member Functions

Protected Attributes

Properties


Detailed Description

Deprecated:
This class is deprecated and will be removed in a future release. BlackBerry Dynamics secures the native NSURLSession and NSURLConnection programming interfaces, which should be used instead. For reference, see NSURLSession Support and GDURLLoadingSystem. For example code, see the RSSReader sample application that comes with the BlackBerry Dynamics SDK for iOS.

This class is for sending Hypertext Transfer Protocol (HTTP) requests, such as GET and POST, from a front-end application on a mobile device to a back-end application server. The application server can be on the Internet, or behind the enterprise firewall. The programming interface is based on the XML Http Request (XHR) standard. HTTPS security is supported.

This programming interface cannot be used until BlackBerry Dynamics authorization processing is complete.

Note that synchronous request calls should not be made from the main application thread.

See also:
GDiOS, for BlackBerry Dynamics authorization
Manuals page for the BlackBerry Dynamics enterprise servers for the Platform Overview.
Thread support statement
Background Execution
GDSocket
GDNetUtility
XML HTTP Request (XHR) specification on w3.org
GDURLLoadingSystem and NSURLSession Support for alternative approaches.

Overview

An instance of this class represents an HTTP request. The programming interface is state-based. The availability of functions to be called by the application at any given time depend on the current state of the request.

Requests can be processed synchronously or asynchronously, at the option of the application. For asychronous operation, the application attaches its own event-handler callback to the request object. The callback function is invoked when events occur, or when the request changes state.

The callback is attached through a delegate class. Invocation of the callback is detailed in the delegate class's documentation, see GDHttpRequestDelegate.

The availability of interface functions, and what actions take place, are detailed below and summarized in the following table. (States in all-capitals are standard XHR ready states.)

Ready StateFunctions / Actions
UNSENT

The application can call open: state becomes OPENED

The application can also call any of the following pre-send functions:
disableHostVerification (deprecated),
disablePeerVerification (deprecated),
disableFollowLocation (deprecated),
disableCookieHandling(deprecated),
clearCookies (deprecated),
enableHttpProxy (deprecated),
disableHttpProxy (deprecated)
Calling a pre-send function doesn't cause a state change. The action of a pre-send function will take effect when the request is sent.

OPENED

The application can call send, sendData or sendWithFile: state becomes Sending

The application can also call any of the following, which don't cause a state change:
Any pre-send function that can be called in the UNSENT state,
setRequestHeader (deprecated),
setPostValue (deprecated),
clearPostValues (deprecated)

SENT

The request has been sent to the server

If a response is received, state becomes HEADERS_RECEIVED

If an error occurs, state becomes DONE

HEADERS_RECEIVED

All the headers have been received

The application can call the following, which don't cause a state change:
getResponseHeader (deprecated),
getAllResponseHeaders (deprecated),
getStatus (deprecated),
getStatusText (deprecated)

When the first response data is received, state becomes LOADING

LOADING

The body is being received

The application can call the following, which don't cause a state change:
getResponseHeader (deprecated),
getAllResponseHeaders (deprecated),
getStatus (deprecated),
getStatusText (deprecated),
getReceiveBuffer (deprecated)

Note: getReceiveBuffer is used to access the body of the HTTP response

When the last response data is received, state becomes DONE

DONE

The complete body has been received or an error has occured

The application can call the same functions as when in the UNSENT state

The application can also call the following, which don't cause a state change:
getResponseHeader (deprecated),
getAllResponseHeaders (deprecated),
getStatus (deprecated),
getStatusText (deprecated),
getReceiveBuffer (deprecated)

The transitions in the above table are also shown in the GDHttpRequest state transition diagram (deprecated).

XHR differences

Differences between this programming interface and the XmlHttpRequest standard are detailed below, and summarized in the following table:

XmlHttpRequestGDHttpRequest
readyState attribute getState function
responseText and responseXML attributes,
which provide all data received so far.
getReceiveBuffer function,
which provides data received since last called
status attribute getStatus function
statusText attribute getStatusText function

Enterprise server connection notes

BlackBerry Dynamics secure communication can be used to connect to servers that are behind the enterprise firewall. This applies to socket connections and HTTP requests. Note the following when using this capability.

The addresses of any application servers to which connection is being made must be configured in the enterprise management console. The address could be registered as the application's server, or as an additional server, for example.

Note. The application server configuration set in the management console can be obtained in the application code by using the getApplicationConfig (GDiOS) function.

The connection to the application server will be made through the BlackBerry Dynamics proxy infrastructure. The status of the application's connection to the proxy infrastructure can be checked and monitored by using the GDReachability interface.

See also:
System administration tasks for application developers
GDReachability class reference.

HTTPS Security

BlackBerry Dynamics secure communication supports HTTPS, using a Secure Socket Layer connection or Transport Layer Security (SSL/TLS) to send an HTTP request and receive a response.

Using SSL/TLS requires that the remote end has a suitable certificate, and that the certificate is valid. A number of checks for validity are made by the BlackBerry Dynamics runtime, some of which can be switched off by the application.

A typical HTTPS request sequence would be as follows. The application makes a first attempt to send the HTTPS request. In the first attempt, all checking is switched on. If a security error is encountered, this request will fail. The application can then switch off some checking, and attempt to send a second request to the same address as the first request. With less rigorous checking, the second attempt may succeed where the first failed.

The relevant parts of the programming interface are:

Secure Protocol Selection

Establishing an SSL/TLS connection can involve negotiating and retrying, in order to select a secure protocol that is supported by both client and server. The BlackBerry Dynamics runtime handles client-side negotiation and retrying, if secure communication is in use.

By default, the runtime won't offer the TLSv1.1 or TLSv1.2 protocols for SSL/TLS connections with an application server.

The runtime can be configured to offer these protocols, as follows.

  1. Add a new row to the application's Info.plist file*:
    • Key: GDControlTLSVersions
    • Type: String (the default)
  2. Set the value to:
    • GDEnableTLS1.1 to enable the TLSv1.1 protocol.
    • GDEnableTLS1.2 to enable both TLSv1.1 and TLSv1.2 protocols.
    As an alternative, the value can instead be an array containing one or both of the above strings as separate items.

(*In case there are multiple Info.plist files, check that the correct one has been edited by opening the Info tab of the application target being built. The setting just made should appear there.)

The setting only affects connections to application servers, not the connection with the BlackBerry Dynamics infrastructure itself. The protocols aren't offered by default because there are many installed web servers with which a connection cannot be established after one of these protocols has been offered.

In addition to the above, the following protocol versions can be blocked by enterprise management console configuration.

  • SSLv3
  • TLSv1.0
  • TLSv1.1
  • TLSv1.2

The configuration of blocked protocol versions can be done in the enterprise management console user interface. The configuration applies at the deployment level and isn't specific to user, policy group, or application server. The block only affects communication with application servers that is routed via the BlackBerry Dynamics proxy infrastructure.

HTTP proxy support

HTTP and HTTPS requests can be relayed by an HTTP or HTTPS proxy that resides on the Internet or behind the enterprise firewall. Authentication with the proxy is supported.

See the enableHttpProxy: and disableHttpProxy reference documentation for details.

When making HTTPS requests through an HTTP proxy, SSL/TLS certificate verification must be switched off. Certificate verification while using an HTTP proxy isn't supported. See under HTTPS Security, above. BlackBerry Dynamics HTTP data communication doesn't go via the proxy specified in the device's native settings, if any.

HTTP authentication

The BlackBerry Dynamics runtime supports the following mechanisms for authentication with HTTP servers: Basic Access, Digest Access, NTLM, and Kerberos. Except for Kerberos, all these mechanisms are also supported for authentication with HTTP proxies.

Kerberos Authentication

The BlackBerry Dynamics runtime supports Kerberos version 5 authentication. If using Kerberos authentication:

  • Supply username and password credentials as documented in the relevant function references.
  • The username must be in the user@realm long form. The short form shortrealm\user isn't supported.
  • The BlackBerry Dynamics runtime will use these credentials to request Kerberos tickets. The tickets are persisted on the device in the BlackBerry Dynamics secure store. (The ticket store isn't generally accessible to the application, but see clearCredentialsForMethod:.)
  • The stored Kerberos tickets are then used to authenticate the user on any site that supports Kerberos authentication. So long as the ticket continues to be accepted, there is no need for credentials to be supplied again, and no authentication challenge.
  • This continues until a site doesn't accept the stored ticket (e.g. the ticket has expired and cannot be renewed).
  • The Kerberos realm must be accessible. One way is to configure the Kerberos realm as an Additional Server in the enterprise management console.
  • Kerberos realms are treated differently to server addresses. An unqualified server address may be resolved according to configuration in the enterprise management console, but the short form of a Kerberos realm cannot be resolved in this way. Note that the short form of the Kerberos realm will typically be the form used when logging in to the enterprise LAN at the desktop. The long form is typically the short form with the domain appended.
  • Kerberos delegation can be allowed or disallowed. See GDCacheController::kerberosAllowDelegation:.

HTTP Cookie Handling

By default, HTTP cookies received through BlackBerry Dynamics secure communication are handled automatically:

The BlackBerry Dynamics cookie store persists between executions of the application, and if the mobile device is switched off. The contents of the store can be managed with the native NSHTTPCookieStorage programming interface, and so can non-persistent cookies received through BlackBerry Dynamics secure communication.

Automatic handling of HTTP cookies received through BlackBerry Dynamics secure communication can be switched off, as follows.

See also:
NSHttpCookieStorage class reference on the apple.com developer website.
NSMutableURLRequest class reference on the apple.com developer website.

Member Function Documentation

- (instancetype) init
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function when constructing a new request. This function doesn't initiate data communication. Compare open and send.

The new request's ready state will be GDHttpRequest_UNSENT.

- (BOOL) open: (const char *)  method
withUrl: (const char *)  url
withAsync: (BOOL)  isAsync
withUser: (const char *)  user
withPass: (const char *)  password
withAuth: (const char *)  auth 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to open the request, and set the main parameters.

This is generally the first function called, after init, when the request's ready state is GDHttpRequest_UNSENT. However, in principle this function can be called at any time, regardless of the ready state. If the ready state isn't GDHttpRequest_UNSENT then an effective abort is executed, before the open call is processed.

This section documents all the parameters that the function supports. It is valid to use all the parameters, or to use particular subsets. The subsequent open sections document the valid subsets of parameters.

Kerberos authentication
To utilize Kerberos authentication, supply the username and password credentials to the initial call to this function. See also under HTTP Authentication, above.
Parameters:
methodNull-terminated case-sensitive string containing the HTTP method that will be sent to the server. Typical values are: "GET", "POST", "HEAD", "OPTIONS", "TRACE", "PUT", "CONNECT". Any other value is sent as a custom method.
urlNull-terminated string containing the Uniform Resource Locator (URL) that will be requested. The URL must be fully qualified, including a scheme, domain, and path. For example: "http://www.example.com/index.html".
isAsyncNO to use synchronous fetching, YES to use asynchronous fetching.
See under send and abort for details of the difference.
userNull-terminated string containing authentication username. For Kerberos, this is in the user@realm format.
passwordNull-terminated string containing authentication password.
authNull-terminated string specifying the authentication scheme:
"BASIC" or a null pointer to use Basic Access authentication.
"DIGEST" to use Digest Access authentication.
"NEGOTIATE" to use negotiated Kerberos authentication, see note above.
"NTLM" to use NTLM authentication.
The following forms of the NTLM authentication protocol are supported: NTLMv1, NTLMv2, and NTLM2 Session.
Returns:
YES if the request was opened.
NO if the parameters were not valid or the request couldn't be opened.

If the request was opened then the ready state changes, to GDHttpRequest_OPENED. If asynchronous fetching was specified, then the delegate onStateChange callback is invoked.

- (BOOL) open: (const char *)  method
withUrl: (const char *)  url
withUser: (const char *)  user
withPass: (const char *)  password
withAuth: (const char *)  auth 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call with these parameters to open the request with authentication and synchronous fetching. See open for full details.

- (BOOL) open: (const char *)  method
withUrl: (const char *)  url
withAsync: (BOOL)  isAsync 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call with these parameters to open the HTTP request specifying synchronous or asynchronous fetching. The request will not use any new authentication.

If Kerberos authentication is in use then existing Kerberos tickets will be attempted if the server returns an HTTP 401 response requesting to Negotiate Authentication.

See open for full details.

- (BOOL) open: (const char *)  method
withUrl: (const char *)  url 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call with these parameters to open the HTTP request with synchronous fetching. The request will not use any new authentication.

If Kerberos authentication is in use then existing Kerberos tickets will be attempted if the server returns an HTTP 401 response requesting to Negotiate Authentication.

See open for full details.

- (BOOL) disableHostVerification
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to switch off host name verification, when making an HTTPS request. Host name verification is an SSL/TLS security option.

Host Name Verification
When negotiating an SSL/TLS connection, the server sends a certificate indicating its identity. The certificate includes a number of host names. By default, when using HTTPS, one of the host names in the certificate must match with the host name in the URL being opened, or the connection fails.
If host name verification is switched off, the connection succeeds regardless of whether there is a matching host name in the certificate.
If switched on, the BlackBerry Dynamics runtime checks server identity in a way that conforms with the relevant RFC. See under section 3.1 Server Identity, in RFC 2818.

Note that connections may remain open after the HTTP transaction completes. Even if another instance of GDHttpRequest is constructed, the connection may still be reused. If subsequent transactions to the server require host verification, close must be called immediately after the last unverified transaction completes.

See also:
HTTPS Security, above.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_UNSENT or GDHttpRequest_OPENED.

Switching off host name verification doesn't switch off authenticity verification, see disablePeerVerification.

Returns:
YES if the security option was switched off. The check won't be made when the request is sent.
NO if the security option couldn't be switched off.

This function doesn't affect the ready state.

- (BOOL) disablePeerVerification
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to switch off certificate authenticity verification, when making an HTTPS request. Authenticity verification is an SSL/TLS security option.

Certificate Authenticity Verification
When negotiating an SSL/TLS connection, the server sends a certificate indicating its identity. By default, when using HTTPS, the certificate must be verified as trustworthy, or the connection fails. In this context, trustworthiness derives from a chain of digital signatures, rooted in a certification authority.
If authenticity verification is switched off, the connection succeeds regardless of the certificate's trustworthiness.
If authenticity verification is switched on, the BlackBerry Dynamics runtime checks certificate trustworthiness using operating system services. See the Certificate, Key, and Trust Services API Reference on the apple.com developer website.

Note that connections may remain open after the HTTP transaction completes. Even if another instance of GDHttpRequest is constructed, the connection may still be reused. If subsequent transactions to the server require peer verification, close must be called immediately after the last unverified transaction completes.

See also:
HTTPS Security, above.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_UNSENT or GDHttpRequest_OPENED.

Switching off authenticity verification implicitly also switches off host name verification, see disableHostVerification.

Returns:
YES if the security option was switched off. The check won't be made when the request is sent.
NO if the security option couldn't be switched off.

This function doesn't affect the ready state.

- (BOOL) disableFollowLocation
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to switch off automatic redirection.

If automatic redirection is switched off, the application must handle redirection itself, including handling Location: headers, and HTTP statuses in the 30x range.

If automatic redirection is switched on, any Location: header that the server sends as part of an HTTP header will be automatically followed. This means that the same request will be re-sent to the new location. The re-sent request may itself be redirected, receiving a new Location: header. Automatic redirection continues until a request receives no location headers.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_UNSENT or GDHttpRequest_OPENED.

Returns:
YES if the option was switched off and any Location: headers won't be followed.
NO if the option couldn't be switched off.

This function doesn't affect the ready state.

- (BOOL) disableCookieHandling
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to switch off automatic cookie handling.

If automatic handling is switched off, the application must store and process cookies itself.

When automatic handling is switched on, the BlackBerry Dynamics runtime processes and stores HTTP cookies automatically, as described under HTTP Cookie Handling, above.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_UNSENT or GDHttpRequest_OPENED.

Returns:
YES if the option was switched off.
NO if the option couldn't be switched off.

This function doesn't affect the ready state.

- (void) clearCookies: (BOOL)  includePersistentStore
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest. Cookies can be directly cleared by using the native NSHTTPCookieStorage programming interface. See under HTTP Cookie Handling, above.

Call this function to clear cookies that were automatically stored. Cookies can be cleared from memory only, or from the persistent cookie store too. If cleared from memory only, cookies will still be reloaded from the persistent cookie store when the application is next launched.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_UNSENT or GDHttpRequest_OPENED.

This function is most useful if automatic cookie handling is swiched on. See the disableCookieHandling function, above.

This function doesn't affect the ready state.

Parameters:
includePersistentStoreYES to clear cookies from memory and from persistent BlackBerry Dynamics cookie storage.
NO to clear cookies from memory only.
- (BOOL) enableHttpProxy: (const char *)  host
withPort: (int)  port
withUser: (const char *)  user
withPass: (const char *)  password
withAuth: (const char *)  auth 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to set up usage of an HTTP proxy at a specified address, and using specified credentials. The request will be sent through the proxy.

The proxy server can be located behind the enterprise firewall. In this case its address must be registered in the enterprise management console. Registration would usually be as an additional server. See System administration tasks for application developers.

Certificate authenticity verification while using an HTTP proxy isn't supported. When making HTTPS requests through a proxy, SSL/TLS certificate verification must be switched off, see the disablePeerVerification function.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_UNSENT or GDHttpRequest_OPENED.

Parameters:
hostNull-terminated string containing the address of the proxy. Can be either an Internet Protocol address (IP address, for example "192.168.1.10"), or a fully qualified domain name (for example "www.example.com").
portNumber of the port on the proxy to which connection will be made.
userNull-terminated string containing the proxy authentication username.
passwordNull-terminated string containing the proxy authentication password.
authNull-terminated string specifying the proxy authentication scheme:
"BASIC" or any other value to use Basic Access authentication.
"DIGEST" to use Digest Access authentication.
"NTLM" to use NTLM authentication.
The following forms of the NTLM authentication protocol are supported: NTLMv1, NTLMv2, and NTLM2 Session.
Returns:
YES if sending through an HTTP proxy was configured OK.
NO if configuration failed.

This function doesn't affect the ready state.

- (BOOL) enableHttpProxy: (const char *)  host
withPort: (int)  port 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to set up usage of an HTTP proxy at a specified address. No authentication will be used when connecting to the proxy.

See enableHttpProxy for full details.

- (BOOL) disableHttpProxy
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to remove an HTTP proxy configuration that was previously set, using an enableHttpProxy function. The request then won't be sent through an HTTP proxy.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_UNSENT or GDHttpRequest_OPENED.

Returns:
YES if the HTTP proxy configuration was removed.
NO if removal failed.

This function doesn't affect the ready state.

- (BOOL) setRequestHeader: (const char *)  header
withValue: (const char *)  value 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to add a header field to the HTTP request. This is for standard HTTP header fields such as "Authorization". Add headers after the request is open, but before sending.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_OPENED.

This function can be called zero or more times, because not all HTTP requests will require headers to be added by the application.

Parameter data is copied and stored internally. The application doesn't need to keep the data after calling the function.

Parameters:
headerNull-terminated string containing the name of the header field to add.
valueNull-terminated string containing the value to put in the header field.
Returns:
YES if the header was added OK.
NO if the header couldn't be added.

This function doesn't affect the ready state.

- (void) setPostValue: (const char *)  value
forKey: (const char *)  key 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to add a name-value pair to the HTTP request. The request method must be "POST". Multiple name-value pairs can be added, by calling this function multiple times.

When the request is sent, name-value pairs will be encoded in the request body in a way that is compatible with HTML form submission. No other body data can be passed in the send call.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_OPENED.

Parameters:
valueNull-terminated string containing the value to be set.
keyNull-terminated string containing the name associated with the value.

This function doesn't affect the ready state.

- (void) clearPostValues
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to remove all name-value pairs from the HTTP request. Name-value pairs would have been added with the setPostValue function, see above.

Note that all name-value pairs will be cleared anyway when the request is re-opened. This function need only be called if it is required to clear name-value pairs before sending.

This function should be called before send has been called, when the request's ready state is GDHttpRequest_OPENED.

This function doesn't affect the ready state.

- (BOOL) send: (const char *)  data
withLength: (unsigned int)  len
withTimeout: (int)  timeout_s 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to send the HTTP request to the server.

This section documents all the parameters that the function supports. It is valid to use all the parameters, or to use particular subsets. The subsequent send sections document the valid subsets of parameters.

This function can only be called after open has succeeded, when the ready state is GDHttpRequest_OPENED. The subsequent behavior of send depends on the kind of fetching that was specified in the open call. See the isAsync parameter to open, above.

If synchronous fetching was specified, then the send call returns when HTTP response data is received from the server.

If asynchronous fetching was specified, then the send call returns immediately. The following state transitions then take place as the request progresses.

  1. GDHttpRequest_SENT when the HTTP request has been sent.
  2. GDHttpRequest_HEADERS_RECEIVED when the HTTP response headers have been received.
  3. GDHttpRequest_LOADING when the first HTTP response data is received.
  4. GDHttpRequest_DONE when all HTTP response data has been received.

If an error is encountered, in any state, then the request makes an immediate transition to the GDHttpRequest_DONE state. This includes connection errors, security errors, and time out expiry. (See also the Ready State table in the class documentation, above.)

Parameters:
dataPointer to the HTTP request body. This would be used in, for example, a "POST" method request. Parameter data isn't copied. The application must ensure that the data remains available until the request is in the GDHttpRequest_DONE state.
lenNumeric value for the number of bytes in the request body, i.e. what is pointed to by the data parameter.
timeout_sLength of time out in seconds, or 0 (zero) for never. If the function is called without this parameter, see below, zero is assumed.
Returns:
YES if the request was accepted.
NO if the parameters were invalid.

If the request was sent, and asynchronous fetching was specified, then a state transition should be expected. The next state would be GDHttpRequest_HEADERS_RECEIVED if the request is proceeding, or GDHttpRequest_DONE if there is a connection failure.

See also:
sendWithFile
sendData
- (BOOL) send: (const char *)  data
withTimeout: (int)  timeout_s 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to send an HTTP request with body, and specified time out. The body must be null-terminated.

See send for details.

- (BOOL) send: (const char *)  data
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to send an HTTP request with body, and the default time out setting. The body must be null-terminated.

See send for details.

- (BOOL) send
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to send an HTTP request that has no body, for example a "GET" method request, using the default time out setting.

To send an HTTP request with no body, and override the time out setting, use the full form of send but pass a null pointer as the data parameter.

See send for details.

- (BOOL) sendData: (NSData *)  data
withTimeout: (int)  timeout_s 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to send an HTTP request with body, and specified time out. The body will be the contents of an NSData object.

See send for details.

- (BOOL) sendData: (NSData *)  data
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to send an HTTP request with body, and the default time out setting. The body will be the contents of an NSData object.

See send for details.

- (BOOL) sendWithFile: (NSString *)  pathAndFileName
withTimeout: (NSTimeInterval)  timeoutSeconds 
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to use the open HTTP request to upload a file. The HTTP request's method will be overridden to "PUT" unless it is a custom method. A time out can be specified.

This function causes the HTTP request to be sent, similar to the send function, above. The body of the request will be the contents of the specified file.

The file will not be deleted after it is uploaded. Uploading directly from the BlackBerry Dynamics secure file system isn't supported.

Parameters:
pathAndFileNameNSString containing the path (optional) and filename of the file to upload. If path is omitted, the file is read from the current working directory.
timeoutSecondsLength of time out in seconds, or 0 (zero) for never. If the function is called without this parameter, see below, zero is assumed.
Returns:
YES if the request was accepted.
NO if the parameters were invalid.
See also:
send for other details of sending.
open for how to set the request method.
- (BOOL) sendWithFile: (NSString *)  pathAndFileName
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to send the HTTP request, reading the body of the request from a file, with the default time out setting.

See sendWithFile for details.

- (GDHttpRequest_state_t) getState
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

This function returns the ready state of the HTTP Request. See the GDHttpRequest_state_t documentation for a list of values and ready states. This function is generally the first function called in the delegated event handler, see GDHttpRequestDelegate.

This function corresponds to the standard XHR read-only attribute, readyState.

Returns:
Numeric value that can be compared to the GDHttpRequest_state_t enumerated constants.
- (const char*) getResponseHeader: (const char *)  header
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to obtain a specific HTTP response header. (Compare getAllResponseHeaders.) HTTP response headers will be sent by the server as part of its response to the HTTP request. Response headers are sent before the content part of the response. (Compare getReceiveBuffer.)

If asynchronous fetching is in use, this function can be used after the send call has been made and the request's ready state has progressed to GDHttpRequest_HEADERS_RECEIVED.
If synchronous fetching is in use, this function can be used after send has returned. (By that time, the ready state will already have progressed to GDHttpRequest_DONE.)

Parameters:
headerNull-terminated string containing the name of the required HTTP response header field.
Returns:
Null-terminated string containing the value of the specified header, if present.
Empty string if the server did not send the specified header, or if there was an error and the request never reached the server.
- (const char*) getAllResponseHeaders
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to obtain all HTTP response headers. (Compare getResponseHeader:.) HTTP response headers will be sent by the server as part of its response to the HTTP request. Response headers are sent before the content part of the response. (Compare getReceiveBuffer.)

This function can be used at the same point in the HTTP request cycle as getResponseHeader, see above.

Returns:
Null-terminated string containing all HTTP response header fields, and their values.
  • Different headers will be separated by newline characters.
  • On each line, field and value will be separated by a colon (:) character.
This function doesn't affect the ready state.
- (int) getStatus
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to determine the success or failure of the HTTP request. If the request was sent OK, this function returns the status code received from the HTTP server, which could be a success code or an error code. Otherwise, if the request was not sent, or there was a connection failure, this function returns zero.

In normal HTTP request processing, the status code is sent before the content of the response. (Compare getReceiveBuffer.)

This function can be used at the same point in the HTTP request cycle as getResponseHeader see above.

This function corresponds to the standard XHR read-only attribute, status.

Returns:
Numeric value for the final request status, interpreted as follows:
0 (zero)
Server connection failed.
This includes:
  • DNS errors, or other problems where a connection to the server couldn't even be established.
  • Certificate verification failures, when HTTPS is in use.
  • Connection failure during receipt of the HTTP response.
  • Time out expiry while waiting for the server.
  • Connection closure initiated by the application, see abort.
200 to 299
HTTP request successful at server.
The number is the success code returned by the server.
Other values.
HTTP request failed at server.
This the includes all the standard HTTP errors, such as: 404 'Not found' or 403 'Forbidden'.

Note that, when asynchronous fetching is in use, it is possible that this function returns different values at different points in the request cycle. For example, suppose there is a network failure during receipt of a long response. When the GDHttpRequest_LOADING state is entered, 200 might be returned. But, when the request later enters the GDHttpRequest_DONE state after the connection failure, 0 would be returned.

See also:
  • getStatusText
- (const char*) getStatusText
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

This function returns the status message received from the HTTP server, if the request was sent OK. If the request was not sent, or there was a connection failure, this function will return a description of the condition that caused the failure.

The status message is sent at the same time as the status code, see getStatus above.

This function can be used at the same point in the HTTP request cycle as getResponseHeader, see above.

This function corresponds to the standard XHR read-only attribute, statusText.

Returns:
Null-terminated string containing the status text. The contents depend on the getStatus return code, as follows:
getStatus return codeMessage contents
0 (zero)
Connection failure.
Description of the error condition that caused the failure. For example:
SSL/TLS negotiation failed
Other values
Request sent OK.
Success or failure message provided by the HTTP server.
In the failure case, this includes the standard HTTP errors, such as: 404 'Not found' or 403 'Forbidden'.
See also:
  • getStatus
- (GDDirectByteBuffer*) getReceiveBuffer
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to obtain the response data, i.e. the body of the HTTP response. Response data will be sent by the server as part of its response to the HTTP request. Response data is sent after response headers. (Compare getResponseHeader: and getAllResponseHeaders.)

If asynchronous fetching is in use, this function can be used after the send call has been made and the request's ready state has progressed to GDHttpRequest_LOADING.
If synchronous fetching is in use, this function can be used after send has returned. (By that time, the ready state will already have progressed to GDHttpRequest_DONE.)

The first time this function is called, all data received so far is returned. Subsequent calls return only the data received since the previous call. (If synchronous fetching is in use, then this function would only be called once per request, and would return all the response data.)

This function corresponds to the standard XHR read-only attributes, responseText and responseXML.

Returns:
Pointer to a GDDirectByteBuffer object that contains the response data received since last called.
The application must read the data prior to releasing or re-using the request object.

This function doesn't affect the ready state.

- (BOOL) close
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to force closure of all connections that were used by the HTTP request, after the request has completed. If any default options were switched off then these will be switched back on when the first connection is re-opened. (See also the disableHostVerification, disablePeerVerification and other disable functions, above.)

This function should only be called if the following all apply.

  • Some options were switched off when the request was sent.
  • A new request will be sent to the same endpoint.
  • For the new request, one or more of the options that were switched off are to be switched on.

Connections may remain open after the HTTP transaction completes. Even if another instance of GDHttpRequest is constructed, connections may still be reused. Calling this function immediately after the transaction completes will ensure that connections are closed, and any SSL/TLS verifications that were switched off are switched back on.

After calling this function, it may take longer to make another HTTP request to the same host.

This function can be called when the ready state is GDHttpRequest_DONE. Compare abort.

Returns:
YES if the request was closed and the options reset.
NO if the request couldn't be closed.

This function doesn't affect the ready state.

- (BOOL) abort
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Call this function to cancel the HTTP request. Any response data that had been received will be discarded. Any HTTP request headers that were set will be cleared. Further changes also take place, depending on the request's ready state.

If the ready state is GDHttpRequest_SENT or GDHttpRequest_HEADERS_RECEIVED or GDHttpRequest_LOADING, then the ready state is set to GDHttpRequest_DONE and the delegated event handler is invoked. See GDHttpRequestDelegate. The final status will be set to zero, i.e. getStatus will return 0.

If the ready state is GDHttpRequest_DONE, GDHttpRequest_OPENED, or GDHttpRequest_UNSENT, then this function does nothing and returns NO.

Returns:
YES if the request was aborted.
NO if the request couldn't be aborted, hadn't been sent, or had already completed.

Member Data Documentation

- (__weak id<GDHttpRequestDelegate>) delegate [protected]

Property Documentation

- (BOOL) enablePipelining [read, write, assign]
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

Set this property to enable and disable HTTP pipelining of the associated request.

If pipelining is enabled, then the BlackBerry Dynamics runtime may pipeline the request with other requests to the same server. If pipelining is disabled then the runtime won't pipeline the request.

This property should be set before send has been called, when the request's ready state is GDHttpRequest_UNSENT or GDHttpRequest_OPENED.

Setting this property doesn't affect the ready state.

Set this property to YES to enable HTTP pipelining, or to NO to disable HTTP pipelining. By default, HTTP pipelining is enabled.

- (id<GDHttpRequestDelegate>) delegate [read, write, assign]
Deprecated:
This function is deprecated and will be removed in a future release. It is in a deprecated class, GDHttpRequest.

The GDHttpRequest interface can operate asynchronously, at the option of the application. See isAsync under the open function, above.

If operating asynchronously, when the ready state changes or response data is received, a callback function in the application code is invoked by the BlackBerry Dynamics runtime.

Set this property to an instance of a class that contains the code for the required callback function, i.e. a class that implements the GDHttpRequestDelegate protocol.


The documentation for this class was generated from the following file: