API Guide Home (Online version only) |

# PalmBGService.h

Go to the documentation of this file.

    00001 /*******************************************************************************
    00002  * Copyright (c) 2004-2005 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  ******************************************************************************/
    00005 /**
    00006  * @defgroup    BGService Background Service Library
    00007  * @brief       This library provides support for applications to perform background
    00008  *              network request bypassing NetLib through the default connection.
    00009  *
    00010  * Application can use this library to connect to a server on a network and perform
    00011  * network request by sending protocol-specific string and receiving the returned response.
    00012  * Applications can also utilize this library to make background HTTP request by connecting
    00013  * to a web server at port 80 and sending HTTP GET/POST string with specific URL.
    00014  *
    00015  * Network requests are queued up and the responses are returned through the callback function
    00016  * that is passed to the network request API.
    00017  *
    00018  * @{
    00019  * @}
    00020  */
    00021 /**
    00022  * @ingroup BGService
    00023  */
    00024
    00025 /**
    00026  * @file    PalmBGService.h
    00027  * @version 1.0
    00028  * @brief   Public 68K header file for palmOne Background Network Service Library
    00029  *
    00030  * This file contains the function prototypes and structures for the Background Service which
    00031  *        lets users make a background network connection.
    00032  * <hr>
    00033  */
    00034
    00035 #ifndef __PALMBGSERVICE_H__
    00036 #define __PALMBGSERVICE_H__
    00037
    00038 #include <PalmTypes.h>
    00039 #include <LibTraps.h>
    00040
    00041
    00042 /**
    00043  * @name Function Traps
    00044  *
    00045  */
    00046 /*@{*/
    00047 #define bgTrapAPIVersion            (sysLibTrapCustom+0)    /**<        */
    00048 #define bgTrapCancelRqst            (sysLibTrapCustom+1)    /**<        */
    00049 #define bgTrapINetLibRqst           (sysLibTrapCustom+3)    /**<        */
    00050 #define bgTrapNetLibRqst            (sysLibTrapCustom+4)    /**<        */
    00051 /*@}*/
    00052
    00053 /**
    00054  * @name Library Constants
    00055  *
    00056  */
    00057 /*@{*/
    00058 #define bgServiceLibName        "BGService.Lib"     /**< Background services library name. */
    00059 #define bgServiceCreatorID      'asc9'          /**< Background services Creator ID. */
    00060 #define bgServiceType           'appl'          /**< Background services Type. */
    00061 /*@}*/
    00062
    00063
    00064 /**
    00065  * @name Error Codes
    00066  *
    00067  */
    00068 /*@{*/
    00069 #define IBG_SUCCESS         0   /**< Return Value indicating success.*/
    00070
    00071
    00072 #define IBG_ERRNOTPOSSIBLE  2   /**< Return Value indicating on i705 that radio is NOT on or WebClipping is
    00073                   *  NOT configured in i705 Wireless panel.
    00074                                   */
    00075
    00076 #define IBG_ERRTIMEOUT      3   /**< Return Value indicating the request made could not be
    00077                   *  completed because of a network timeout, or request took longer than
    00078                   *  20 minutes to complete for BGServiceNetRqst() or greater than 2
    00079                   *  minutes for BGServiceINetRqst().
    00080                                   */
    00081
    00082 #define IBG_ERRREQUEST      4   /**< Return Value indicating an error occurred processing the request.  If
    00083                   *  a network error occurred, look at the protocolErr and protocolErrString
    00084                   *  members in the returned BGResult value for details.
    00085                                   */
    00086
    00087
    00088
    00089 #define IBG_ERRRSPTOOBIG    6   /**< Return Value indicating the response handle passed with the request is not
    00090                   *  large enough to contain the response gotten from the server.  In this case
    00091                   *  a partial response may be contained in the response handle, but it is
    00092                   *  truncated.
    00093                                   */
    00094
    00095 #define IBG_ERRSHUTDOWN     7   /**< Return Value indicating the BGService cannot process the request due to a
    00096                   *  HotSync or systen reset occurring
    00097                                   */
    00098
    00099 #define IBG_ERRRQSTDONE     8   /**< Return Value indicating a request cannot be cancelled with BGServiceCancelRqst()
    00100                   *  because the request was already started.
    00101                                   */
    00102
    00103 #define IBG_MAXBUFSZ        100   /**< Maximum size of protocolErrString. */
    00104 /*@}*/
    00105
    00106 /**
    00107  * @brief Structure containing Result of response for a protocol request
    00108  */
    00109 typedef struct
    00110 {
    00111     UInt32  majorResult;                      /**< One of the above defined return values */
    00112     UInt32  protocolErr;                      /**< Any protocol specific error code, if any */
    00113     char    protocolErrString[IBG_MAXBUFSZ];  /**< Any protocol err response from the server */
    00114
    00115 } BGResult;
    00116
    00117
    00118 /********************************************************************
    00119  * Prototypes
    00120  ********************************************************************/
    00121 #ifdef __cplusplus
    00122 extern "C" {
    00123 #endif
    00124
    00125 /**
    00126  * @brief Opens the Background Service library.
    00127  *    This function should be called prior to calling the other Background Service functions.
    00128  *
    00129  * @param libRefNum:    IN:  Reference number of the Background Service library.
    00130  * @return The error code returned from the library. If this is errNone, the
    00131  *     function was sucessful.
    00132  *
    00133  * @code
    00134  * UInt16 bgServiceLibRefNum = 0;
    00135  * err = SysLibFind(bgServiceLibName, &bgServiceLibRefNum);
    00136  * if( err == sysErrLibNotFound )
    00137  * {
    00138  *     err = SysLibLoad(bgServiceType, bgServiceCreatorID, &bgServiceLibRefNum);
    00139  *         if( !err ) {
    00140  *             err = BGServiceOpen(bgServiceLibRefNum);
    00141  *         }
    00142  * } @endcode
    00143  *
    00144  * @see BGServiceClose
    00145  */
    00146 extern Err BGServiceOpen( UInt16 libRefNum )
    00147                 SYS_TRAP( sysLibTrapOpen );
    00148
    00149 /**
    00150  * @brief Closes the Background Service library.
    00151  *    This function should be called after your application has finished with the Background Service
    00152  *    library.
    00153  *
    00154  * @param libRefNum:    IN:  Reference number of the Background Service  library.
    00155  * @return The error code returned from the library. If this is errNone, the
    00156  *     function was sucessful.
    00157  *
    00158  * @code
    00159  * err = BGServiceClose(bgServiceLibRefNum);@endcode
    00160  *
    00161  * @see BGServiceOpen
    00162  */
    00163 extern Err BGServiceClose( UInt16 libRefNum )
    00164                 SYS_TRAP( sysLibTrapClose );
    00165
    00166 /**
    00167  * @brief Returns the version number of Background Service
    00168  *
    00169  * @param libRefNum:    IN:  Reference number of the library.
    00170  * @param pversion: IN:  Pointer to version number returned
    00171  *
    00172  * @return Always IBG_SUCCESS
    00173  */
    00174 extern Err BGServiceVersion( UInt16 libRefNum, UInt32 *pversion )
    00175                 SYS_TRAP( bgTrapAPIVersion );
    00176
    00177
    00178 /**
    00179  * @brief Cancels a current request identified by the Request id
    00180  *
    00181  * @param libRefNum:    IN:  Reference number of the library.
    00182  * @param rqstId:   IN:  Request ID of the BgRequest to be cancelled.
    00183  *
    00184  * @return IBG_SUCCESS on success, otherwise IBG_ERRRQSTDONE if request
    00185  *         was not found or has begun already.
    00186  */
    00187 extern Err BGServiceCancelRqst( UInt16 libRefNum, UInt32 rqstId )
    00188                 SYS_TRAP( bgTrapCancelRqst );
    00189
    00190
    00191 /**
    00192  * @brief Background Request's Response Callback function.
    00193  *
    00194  * @param rqstId    IN:  Request id that identifies a particular request the response is for
    00195  * @param presult   IN:  Contains the response protocol error message if any.
    00196  * @param responseH IN:  Handle to the response string.
    00197  * @param respSz    IN:  Size of response
    00198  * @param opaque    IN:  Opaque value passed back to the callback, can be used for userdata
    00199  * @return One of the IBG_xxx return codes defined above.  Currently any return
    00200  *         value is ignored.
    00201  */
    00202 typedef UInt32 ( * BGRecvResponseFP )( UInt32 rqstId, BGResult *presult, MemHandle *responseH,
    00203                                        UInt32 respSz, UInt32* opaque );
    00204
    00205
    00206 /**
    00207  *
    00208  * @brief Perform a INetLib request via the HTTP POST command
    00209  *
    00210  * @param libRefNum:    IN:  Reference number of the library.
    00211  * @param purl:     IN:  Url of server to issue request to.  Formatted for INetLibURLCrack command
    00212  * @param ppostBuf:     IN:  Any post data for request, formatted for INetLibSockHTTPReqSend command -
    00213  *                           No additional formatting is performed.
    00214  * @param precvFunc:    IN:  Response callback function
    00215  * @param opaque:   IN:  Opaque value passed back to callback routine when called
    00216  * @param respH:    IN:  Pre-allocated memory handle to hold response.  Must be big enough to hold
    00217  *                           largest response ( for INet typically less than 10K )
    00218  * @param prqstId:  IN:  Returned id given to request for later identification or canceling
    00219  *
    00220  * @return IBG_SUCCESS if accepted, otherwise another error code defined above
    00221  */
    00222 extern Err BGServiceINetRqst( UInt16 libRefNum, char *purl, char *ppostBuf, BGRecvResponseFP precvFunc,
    00223                               UInt32 opaque, MemHandle respH, UInt32 *prqstId )
    00224                 SYS_TRAP( bgTrapINetLibRqst );
    00225
    00226 /**
    00227  *
    00228  * @brief Perform a NetLib request on the default network connection ( for now )
    00229  *
    00230  * @param libRefNum:    IN:  Reference number of the library.
    00231  * @param notUsed:  IN:  Always pass NULL.
    00232  * @param pserver:  IN:  Server to issue request to.  Hostnames are looked up via DNS calls,
    00233  *                           although slows down requests.  Better to use IP addresses if possible.
    00234  * @param port:     IN:  Port to make call on
    00235  * @param prqst:    IN:  Protocol specific string to make once connection is made to server.
    00236  * @param pterm:    IN:  Server response terminator to look for to know have gotten complete
    00237  *                           response from server, or 0 if don't have a terminator.  Of course
    00238  *                           using a terminator greatly speeds up receiving response.
    00239  * @param precvFunc:    IN:  Response callback function
    00240  * @param opaque:   IN:  Opaque value passed back to callback routine when called
    00241  * @param reserved: IN:  Reserved for future use, must always be 0
    00242  * @param respH:    IN:  Pre-allocated memory handle to hold response.  Must be big enough to hold
    00243  *                           largest response ( for INet typically less than 10K )
    00244  * @param prqstId:  IN:  Returned id given to request for later identification or canceling
    00245  *
    00246  * @return IBG_SUCCESS if accepted, otherwise another error code defined above
    00247  ***/
    00248 extern Err BGServiceNetRqst( UInt16 libRefNum, char *notUsed, char *pserver, UInt16 port,
    00249                              char *prqst, char *pterm, BGRecvResponseFP precvFunc, UInt32 opaque,
    00250                              UInt8 reserved, MemHandle respH, UInt32 *prqstId )
    00251                 SYS_TRAP( bgTrapNetLibRqst );
    00252
    00253
    00254
    00255
    00256 #ifdef __cplusplus
    00257 }
    00258 #endif
    00259
    00260 #endif // __PALMBGSERVICE_H__

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