Delegate for handling GDPushChannel state transitions and received Push Channel notifications (deprecated). More...
#import <GDPush.h>
State changes that occur when using GDPushChannel are handled by creating a class that implements this protocol. The callback for handling received Push Channel notifications is also part of this protocol.
The following code snippets illustrate some common tasks.
-(void)onChannelOpen:(NSString*)token
{
NSLog(@"onChannelOpen token: %@", token);
myApp.pushIsOpen = YES;
myApp.pushToken = token;
[myApp sendPushToken];
}
The above snippet shows a simple onChannelOpen
handler. The following takes place when the Push Channel is opened:
sendPushToken
function is calledThe sendPushToken
function, which would be written by the application developer, would send the token to the application server. This could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.
The server will use the token to address Push Channel notification messages back to the application. These would be received by the application's onChannelMessage handler.
-(void)onChannelMessage:(NSString*)data
{
NSLog(@"onChannelMessage: %@", data);
[myApp processPush:data];
}
The above snippet shows a simple onChannelMessage
handler.
The handler logs the received data to the system monitor, then calls the application processPush
function. The "payload" of the notification is passed as a parameter to the processPush
function.
The processPush
function, which would be written by the application developer, could initiate any of the following actions:
-(void)onChannelClose:(NSString*)data
{
NSLog(@"onChannelClose: %@", data);
myApp.pushIsOpen = NO;
[myApp discardPushToken:data];
}
The above snippet shows a simple onChannelClose
handler. The following takes place when the Push Channel is closed:
discardPushToken
function is called. The token of the closed channel is passed as a parameter.The discardPushToken
function would delete the application's copy of the token, possibly after checking that it matches the whichWas
parameter. The function could also initiate connection of a new Push Channel, which would have a new token. See connect.
-(void)onChannelError:(int)error { NSLog(@"onChannelError: %d", error); myApp.pushIsOpen = NO; myApp.pushErr = error; [myApp discardPushToken]; }
The above snippet shows a simple onChannelError
handler.
The handler logs the error code to the system monitor, flags the channel's state as not connected, records the error code in the application, then calls the application discardPushToken
function.
The discardPushToken
function could do any of the following:
See under onChannelPingFail for an explanation of the Ping Failure feature.
-(void)onChannelPingFail:(int)error { NSLog(@"onChannelPingFail %d", error); if ( error == 605 ) { [myApp resendPushToken]; } }
The above snippet shows a simple onChannelPingFail
handler.
The handler logs the error code to the system monitor, then calls the application resendPushToken
function if the token was lost.
The resendPushToken
function, which would be written by the application developer, would send the application's stored token to the application server. This could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.
The resendPushToken
function should expect that the server is not immediately available, perhaps employing a retry policy.
- (void) onChannelOpen: | (NSString *) | token |
This callback will be invoked when the associated Push Channel is opened in the Good Dynamics proxy infrastructure. See connect. At this point, a Push Channel token will have been issued by the Good Dynamics proxy infrastructure Network Operation Center (NOC).
The function that is invoked must initiate sending of the token to the application server, out of band. The application server will then be able to use the token to address Push Channel notifications back to the application on the device, via the NOC.
Invocation of this callback also notifies the application on the device that any of the following callbacks could now be invoked: onChannelMessage
, onChannelPingFail
, onChannelClose
.
token | NSString containing the Push Channel token issued by the NOC. |
- (void) onChannelMessage: | (NSString *) | data |
This callback will be invoked when a Push Channel notification is received on the associated Push Channel. The message will have been sent by the application server, using the Push Channel notify service, which is hosted by the Good Dynamics Network Operation Center (NOC).
The service supports a "payload" of data to be included in the notification. The data could be in any format chosen by the application developer. The payload could also be empty.
Note that Push Channel notifications can be received at any time when the channel is open. This includes the interval between the request for disconnection (disconnect
called) and channel disconnection being finalized (onChannelClose
received).
The function that is invoked could initiate the following actions:
data | NSString containing the data payload included by the application server, encoded in UTF-8. |
- (void) onChannelClose: | (NSString *) | data |
This callback will be invoked when the associated Push Channel is closed. This means closed by the remote end, or by the application having called disconnect.
Invocation of this callback notifies the application on the device that:
If the onChannelClose
was not expected, the function that is invoked could alert the user that Push Channel notifications will not be received, or cause this to be displayed as an ongoing state. The function could also initiate release of the Push Channel object. Alternatively, reconnection could be initiated, see connect.
data | Token for the Push Channel that was closed. |
Note that this callback is only invoked for permanent Push Channel closure. This callback is not invoked for transient losses of channel communication. For example, this callback is not invoked when the mobile device loses packet data coverage or otherwise cannot connect to the Good Dynamics proxy infrastructure. The status of the connection to the infrastructure can be monitored by using the GDReachability programming interface.
- (void) onChannelError: | (int) | error |
This callback is invoked when a permanent error condition is encountered on the associated Push Channel.
Invocation of this callback notifies the application that the Push Channel token cannot be used any more, or that the channel could not be connected in the first place. Furthermore, no (more) Push Channel notifications will be received on this channel.
The function that is invoked could alert the user that Push Channel notifications will not be received, or cause this to be displayed as an ongoing state. The function that is invoked should initiate reconnection, see connect, after checking that the Push Channel service is available, see GDReachability.isPushChannelAvailable.
error | Reason code for the condition encountered, as follows. |
error | Channel Error reason |
---|---|
0 | Push is not currently connected. |
200-499 | Internal error. |
500-599 | Internal server error. |
- (void) onChannelPingFail: | (int) | error |
This callback is invoked when Ping Failure is encountered on the associated Push Channel.
The function that is invoked should initiate resending of the Push Channel token to the application server, if the token has been lost. This is similar to the processing when the channel is initially opened, see onChannelOpen. If the application server is able to accept the token, then Push Channel notification can resume.
Note that Ping Fail notifications can be received at any time when the channel is open. This includes the interval between the request for disconnection (disconnect
called) and channel disconnection being finalized (onChannelClose
received).
error | Reason code for the condition encountered, as follows. |
error | Ping Failure reason |
---|---|
600 | Application server address could not be resolved via DNS |
601 | Could not connect to application server address |
602 | Application server TLS/SSL certificate invalid |
603 | Timed out waiting for application server HTTP response |
604 | Application server returned an invalid response |
605 | Application server indicated that token is unknown |
Note that only error 605 means that the token has been lost and must be resent.