API Guide Home
(Online version only)

Header Files » Incs » 68k » system

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

Defines

Function Traps
Library Constants
Error Codes

Typedefs

Functions

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