-
- BlackBerry Dynamics
- Runtime library for iOS applications
- 12.0.1.79
Standards-based HTTP request, also supporting HTTPS and communication across the firewall (deprecated). More...
#import <GDNETiOS.h>
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.
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 State | Functions / Actions |
|---|---|
| UNSENT | The application can call open: state becomes OPENEDThe 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 SendingThe 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: |
| LOADING | The body is being received 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 |
Differences between this programming interface and the XmlHttpRequest standard are detailed below, and summarized in the following table:
| XmlHttpRequest | GDHttpRequest |
|---|---|
| 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 |
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.
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:
getStatusText return value will begin with "SSL".disableHostVerification and disablePeerVerification can be used to reduce the level of security checking. Setting disablePeerVerification implicitly sets disableHostVerification.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.
GDControlTLSVersionsString (the default)GDEnableTLS1.1 to enable the TLSv1.1 protocol.GDEnableTLS1.2 to enable both TLSv1.1 and TLSv1.2 protocols.(*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.
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 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.
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.
The BlackBerry Dynamics runtime supports Kerberos version 5 authentication. If using Kerberos authentication:
@realm long form. The short form shortrealm\user isn't supported.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.
GDURLLoadingSystem, such as NSURLSession and NSURLConnection, call the setHTTPShouldHandleCookies: method of the associated NSMutableURLRequest instance.Instance Methods | |
| (instancetype) | - init |
| Initializer that prepares a new request (deprecated). More... | |
| (BOOL) | - open:withUrl:withAsync:withUser:withPass:withAuth: |
| Open the request with all parameters (deprecated). More... | |
| (BOOL) | - open:withUrl:withUser:withPass:withAuth: |
| Open the HTTP request with synchronous fetching (deprecated). More... | |
| (BOOL) | - open:withUrl:withAsync: |
| Open the HTTP request with specified fetching (deprecated). More... | |
| (BOOL) | - open:withUrl: |
| Open the HTTP request with synchronous fetching (deprecated). More... | |
| (BOOL) | - disableHostVerification |
| Security option: Switch off SSL/TLS host name verification (deprecated). More... | |
| (BOOL) | - disablePeerVerification |
| Security option: Switch off SSL/TLS authenticity verification (deprecated). More... | |
| (BOOL) | - disableFollowLocation |
| Switch off automatic redirection (deprecated). More... | |
| (BOOL) | - disableCookieHandling |
| Switch off automatic handling of cookies (deprecated). More... | |
| (void) | - clearCookies: |
| Delete automatically stored cookies (deprecated). More... | |
| (BOOL) | - enableHttpProxy:withPort:withUser:withPass:withAuth: |
| Configure sending through an HTTP proxy with all parameters (deprecated). More... | |
| (BOOL) | - enableHttpProxy:withPort: |
| Configure sending through an HTTP proxy without authentication (deprecated). More... | |
| (BOOL) | - disableHttpProxy |
| Remove HTTP proxy configuration (deprecated). More... | |
| (BOOL) | - setRequestHeader:withValue: |
| Add an HTTP header field (deprecated). More... | |
| (void) | - setPostValue:forKey: |
| Add a name-value pair for a "POST" request (deprecated). More... | |
| (void) | - clearPostValues |
| Clear all name-value pairs (deprecated). More... | |
| (BOOL) | - send:withLength:withTimeout: |
| Send the HTTP request with all parameters (deprecated). More... | |
| (BOOL) | - send:withTimeout: |
| Send the HTTP request with null-terminated body and specified time out (deprecated). More... | |
| (BOOL) | - send: |
| Send the HTTP request with null-terminated body (deprecated). More... | |
| (BOOL) | - send |
| Send the HTTP request without body (e.g. "GET" method) (deprecated). More... | |
| (BOOL) | - sendData:withTimeout: |
| Send the HTTP request with NSData body and specified time out (deprecated). More... | |
| (BOOL) | - sendData: |
| Send the HTTP request with NSData body (deprecated). More... | |
| (BOOL) | - sendWithFile:withTimeout: |
| Send the HTTP request with file contents as body, with specified time out (deprecated). More... | |
| (BOOL) | - sendWithFile: |
| Send the HTTP request with file contents as body, with default time out (deprecated). More... | |
| (GDHttpRequest_state_t) | - getState |
| Get the ready state of the HTTP request (deprecated). More... | |
| (nullable const char *) | - getResponseHeader: |
| Get a specified HTTP response header (deprecated). More... | |
| (nullable const char *) | - getAllResponseHeaders |
| Get all HTTP response headers (deprecated). More... | |
| (int) | - getStatus |
| Get the numeric HTTP response status, or 0 (zero) if an error occurred (deprecated). More... | |
| (nullable const char *) | - getStatusText |
| Get the textual HTTP response status, as sent by the server, or details of error if getStatus returns 0 (deprecated). More... | |
| (nullable GDDirectByteBuffer *) | - getReceiveBuffer |
| Get HTTP response data (deprecated). More... | |
| (BOOL) | - close |
| Close connection and reset options (deprecated). More... | |
| (BOOL) | - abort |
| Cancel the request (deprecated). More... | |
Protected Attributes | |
| __weak id< GDHttpRequestDelegate > _Nullable | delegate |
Properties | |
| BOOL | enablePipelining |
| Enable and disable HTTP pipelining of the request (deprecated). More... | |
| id< GDHttpRequestDelegate > | delegate |
| Handler for state changes and received data (deprecated). More... | |
| - (instancetype) init |
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: | (nullable const char *) | user | |
| withPass: | (nullable const char *) | password | |
| withAuth: | (nullable const char *) | auth | |
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.
| method | Null-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. |
| url | Null-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". |
| isAsync | NO to use synchronous fetching, YES to use asynchronous fetching.See under send and abort for details of the difference. |
| user | Null-terminated string containing authentication username. For Kerberos, this is in the user@realm format. |
| password | Null-terminated string containing authentication password. |
| auth | Null-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. |
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: | (nullable const char *) | user | |
| withPass: | (nullable const char *) | password | |
| withAuth: | (nullable const char *) | auth | |
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 | |
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 | |
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 |
Call this function to switch off host name verification, when making an HTTPS request. Host name verification is an SSL/TLS security option.
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.
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.
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 |
Call this function to switch off certificate authenticity verification, when making an HTTPS request. Authenticity verification is an SSL/TLS security option.
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.
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.
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 |
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.
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 |
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.
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 |
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.
| includePersistentStore | YES 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 | |
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.
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.
| host | Null-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"). |
| port | Number of the port on the proxy to which connection will be made. |
| user | Null-terminated string containing the proxy authentication username. |
| password | Null-terminated string containing the proxy authentication password. |
| auth | Null-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. |
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 | |
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 |
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.
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 | |
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.
| header | Null-terminated string containing the name of the header field to add. |
| value | Null-terminated string containing the value to put in the header field. |
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 | |
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.
| value | Null-terminated string containing the value to be set. |
| key | Null-terminated string containing the name associated with the value. |
This function doesn't affect the ready state.
| - (void) clearPostValues |
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: | (nullable const char *) | data | |
| withLength: | (unsigned int) | len | |
| withTimeout: | (int) | timeout_s | |
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.
GDHttpRequest_SENT when the HTTP request has been sent.GDHttpRequest_HEADERS_RECEIVED when the HTTP response headers have been received.GDHttpRequest_LOADING when the first HTTP response data is received.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.)
| data | Pointer 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. |
| len | Numeric value for the number of bytes in the request body, i.e. what is pointed to by the data parameter. |
| timeout_s | Length of time out in seconds, or 0 (zero) for never. If the function is called without this parameter, see below, zero is assumed. |
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.
| - (BOOL) send: | (nullable const char *) | data | |
| withTimeout: | (int) | timeout_s | |
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: | (nullable const char *) | data |
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 |
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: | (nullable NSData *) | data | |
| withTimeout: | (int) | timeout_s | |
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: | (nullable NSData *) | data |
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 | |
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.
| pathAndFileName | NSString containing the path (optional) and filename of the file to upload. If path is omitted, the file is read from the current working directory. |
| timeoutSeconds | Length of time out in seconds, or 0 (zero) for never. If the function is called without this parameter, see below, zero is assumed. |
YES if the request was accepted. NO if the parameters were invalid.| - (BOOL) sendWithFile: | (NSString *) | pathAndFileName |
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 |
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.
| - (nullable const char*) getResponseHeader: | (const char *) | header |
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.)
| header | Null-terminated string containing the name of the required HTTP response header field. |
| - (nullable const char*) getAllResponseHeaders |
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.
| - (int) getStatus |
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.
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.
| - (nullable const char*) getStatusText |
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.
getStatus return code, as follows:getStatus return code | Message 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'. |
| - (nullable GDDirectByteBuffer*) getReceiveBuffer |
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.
This function doesn't affect the ready state.
| - (BOOL) close |
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.
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.
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 |
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.
YES if the request was aborted. NO if the request couldn't be aborted, hadn't been sent, or had already completed.
|
protected |
|
readwritenonatomicassign |
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.
|
readwritenonatomicweak |
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.