API Guide Home (Online version only) |

# PalmBGService.h File Reference

## Detailed Description

Public 68K header file for palmOne Background Network Service Library.

Version:
  1.0

This file contains the function prototypes and structures for the Background Service which lets users make a background network connection.

Definition in file PalmBGService.h.

Include dependency graph for PalmBGService.h:

Go to the source code of this file.

## Data Structures

- struct BGResult
    Structure containing Result of response for a protocol request. More...

## Defines

Function Traps

- #define bgTrapAPIVersion (sysLibTrapCustom+0)
- #define bgTrapCancelRqst (sysLibTrapCustom+1)
- #define bgTrapINetLibRqst (sysLibTrapCustom+3)
- #define bgTrapNetLibRqst (sysLibTrapCustom+4)

Library Constants

- #define bgServiceLibName "BGService.Lib"
- #define bgServiceCreatorID 'asc9'
- #define bgServiceType 'appl'

Error Codes

- #define IBG_SUCCESS 0
- #define IBG_ERRNOTPOSSIBLE 2
- #define IBG_ERRTIMEOUT 3
- #define IBG_ERRREQUEST 4
- #define IBG_ERRRSPTOOBIG 6
- #define IBG_ERRSHUTDOWN 7
- #define IBG_ERRRQSTDONE 8
- #define IBG_MAXBUFSZ 100

## Typedefs

- typedef UInt32(*) BGRecvResponseFP (UInt32 rqstId, BGResult *presult, MemHandle *responseH, UInt32 respSz, UInt32 *opaque)
    Background Request's Response Callback function.

## Functions

- Err BGServiceOpen (UInt16 libRefNum)
    Opens the Background Service library. This function should be called prior to calling the other Background Service functions.
- Err BGServiceClose (UInt16 libRefNum)
    Closes the Background Service library. This function should be called after your application has finished with the Background Service library.
- Err BGServiceVersion (UInt16 libRefNum, UInt32 *pversion)
    Returns the version number of Background Service.
- Err BGServiceCancelRqst (UInt16 libRefNum, UInt32 rqstId)
    Cancels a current request identified by the Request id.
- Err BGServiceINetRqst (UInt16 libRefNum, char *purl, char *ppostBuf, BGRecvResponseFP precvFunc, UInt32 opaque, MemHandle respH, UInt32 *prqstId)
    Perform a INetLib request via the HTTP POST command.
- Err BGServiceNetRqst (UInt16 libRefNum, char *notUsed, char *pserver, UInt16 port, char *prqst, char *pterm, BGRecvResponseFP precvFunc, UInt32 opaque, UInt8 reserved, MemHandle respH, UInt32 *prqstId)
    Perform a NetLib request on the default network connection ( for now ).

## Define Documentation

#define bgServiceCreatorID 'asc9'

Background services Creator ID.

Definition at line 59 of file PalmBGService.h.

#define bgServiceLibName "BGService.Lib"

Background services library name.

Definition at line 58 of file PalmBGService.h.

#define bgServiceType 'appl'

Background services Type.

Definition at line 60 of file PalmBGService.h.

#define bgTrapAPIVersion (sysLibTrapCustom+0)

Definition at line 47 of file PalmBGService.h.

#define bgTrapCancelRqst (sysLibTrapCustom+1)

Definition at line 48 of file PalmBGService.h.

#define bgTrapINetLibRqst (sysLibTrapCustom+3)

Definition at line 49 of file PalmBGService.h.

#define bgTrapNetLibRqst (sysLibTrapCustom+4)

Definition at line 50 of file PalmBGService.h.

#define IBG_ERRNOTPOSSIBLE 2

Return Value indicating on i705 that radio is NOT on or WebClipping is NOT configured in i705 Wireless panel.

Definition at line 72 of file PalmBGService.h.

#define IBG_ERRREQUEST 4

Return Value indicating an error occurred processing the request. If a network error occurred, look at the protocolErr and protocolErrString members in the returned BGResult value for details.

Definition at line 82 of file PalmBGService.h.

#define IBG_ERRRQSTDONE 8

Return Value indicating a request cannot be cancelled with BGServiceCancelRqst() because the request was already started.

Definition at line 99 of file PalmBGService.h.

#define IBG_ERRRSPTOOBIG 6

Return Value indicating the response handle passed with the request is not large enough to contain the response gotten from the server. In this case a partial response may be contained in the response handle, but it is truncated.

Definition at line 89 of file PalmBGService.h.

#define IBG_ERRSHUTDOWN 7

Return Value indicating the BGService cannot process the request due to a HotSync or systen reset occurring

Definition at line 95 of file PalmBGService.h.

#define IBG_ERRTIMEOUT 3

Return Value indicating the request made could not be completed because of a network timeout, or request took longer than 20 minutes to complete for BGServiceNetRqst() or greater than 2 minutes for BGServiceINetRqst().

Definition at line 76 of file PalmBGService.h.

#define IBG_MAXBUFSZ 100

Maximum size of protocolErrString.

Definition at line 103 of file PalmBGService.h.

#define IBG_SUCCESS 0

Return Value indicating success.

Definition at line 69 of file PalmBGService.h.

## Typedef Documentation

typedef UInt32( * ) BGRecvResponseFP(UInt32 rqstId, BGResult *presult, MemHandle *responseH, UInt32 respSz, UInt32 *opaque)

Background Request's Response Callback function.

Parameters:

  | rqstId | IN: Request id that identifies a particular request the response is for
  | presult | IN: Contains the response protocol error message if any.
  | responseH | IN: Handle to the response string.
  | respSz | IN: Size of response
  | opaque | IN: Opaque value passed back to the callback, can be used for userdata

Returns:
  One of the IBG_xxx return codes defined above. Currently any return value is ignored.

Definition at line 202 of file PalmBGService.h.

## Function Documentation

Err BGServiceCancelRqst | ( | UInt16 | libRefNum,
|  | UInt32 | rqstId |
| ) |  |  |

Cancels a current request identified by the Request id.

Parameters:

  | libRefNum,: | IN: Reference number of the library.
  | rqstId,: | IN: Request ID of the BgRequest to be cancelled.

Returns:
  IBG_SUCCESS on success, otherwise IBG_ERRRQSTDONE if request was not found or has begun already.

Err BGServiceClose | ( | UInt16 | libRefNum | ) |

Closes the Background Service library. This function should be called after your application has finished with the Background Service library.

Parameters:

  | libRefNum,: | IN: Reference number of the Background Service library.

Returns:
  The error code returned from the library. If this is errNone, the function was sucessful.

     err = BGServiceClose(bgServiceLibRefNum);

See also:
  BGServiceOpen

Err BGServiceINetRqst | ( | UInt16 | libRefNum,
|  | char * | purl,
|  | char * | ppostBuf,
|  | BGRecvResponseFP | precvFunc,
|  | UInt32 | opaque,
|  | MemHandle | respH,
|  | UInt32 * | prqstId |
| ) |  |  |

Perform a INetLib request via the HTTP POST command.

Parameters:

  | libRefNum,: | IN: Reference number of the library.
  | purl,: | IN: Url of server to issue request to. Formatted for INetLibURLCrack command
  | ppostBuf,: | IN: Any post data for request, formatted for INetLibSockHTTPReqSend command - No additional formatting is performed.
  | precvFunc,: | IN: Response callback function
  | opaque,: | IN: Opaque value passed back to callback routine when called
  | respH,: | IN: Pre-allocated memory handle to hold response. Must be big enough to hold largest response ( for INet typically less than 10K )
  | prqstId,: | IN: Returned id given to request for later identification or canceling

Returns:
  IBG_SUCCESS if accepted, otherwise another error code defined above

Err BGServiceNetRqst | ( | UInt16 | libRefNum,
|  | char * | notUsed,
|  | char * | pserver,
|  | UInt16 | port,
|  | char * | prqst,
|  | char * | pterm,
|  | BGRecvResponseFP | precvFunc,
|  | UInt32 | opaque,
|  | UInt8 | reserved,
|  | MemHandle | respH,
|  | UInt32 * | prqstId |
| ) |  |  |

Perform a NetLib request on the default network connection ( for now ).

Parameters:

  | libRefNum,: | IN: Reference number of the library.
  | notUsed,: | IN: Always pass NULL.
  | pserver,: | IN: Server to issue request to. Hostnames are looked up via DNS calls, although slows down requests. Better to use IP addresses if possible.
  | port,: | IN: Port to make call on
  | prqst,: | IN: Protocol specific string to make once connection is made to server.
  | pterm,: | IN: Server response terminator to look for to know have gotten complete response from server, or 0 if don't have a terminator. Of course using a terminator greatly speeds up receiving response.
  | precvFunc,: | IN: Response callback function
  | opaque,: | IN: Opaque value passed back to callback routine when called
  | reserved,: | IN: Reserved for future use, must always be 0
  | respH,: | IN: Pre-allocated memory handle to hold response. Must be big enough to hold largest response ( for INet typically less than 10K )
  | prqstId,: | IN: Returned id given to request for later identification or canceling

Returns:
  IBG_SUCCESS if accepted, otherwise another error code defined above

Err BGServiceOpen | ( | UInt16 | libRefNum | ) |

Opens the Background Service library. This function should be called prior to calling the other Background Service functions.

Parameters:

  | libRefNum,: | IN: Reference number of the Background Service library.

Returns:
  The error code returned from the library. If this is errNone, the function was sucessful.

     UInt16 bgServiceLibRefNum = 0;
     err = SysLibFind(bgServiceLibName, &bgServiceLibRefNum);
     if( err == sysErrLibNotFound )
     {
         err = SysLibLoad(bgServiceType, bgServiceCreatorID, &bgServiceLibRefNum);
             if( !err ) {
                 err = BGServiceOpen(bgServiceLibRefNum);
             }
     }

See also:
  BGServiceClose

Err BGServiceVersion | ( | UInt16 | libRefNum,
|  | UInt32 * | pversion |
| ) |  |  |

Returns the version number of Background Service.

Parameters:

  | libRefNum,: | IN: Reference number of the library.
  | pversion,: | IN: Pointer to version number returned

Returns:
  Always IBG_SUCCESS

Top | Palm Developer Network © 2004-2008, Palm, Inc. All rights reserved. Generated on Fri Jun 13 10:07:41 2008 for Palm API Guide