API Guide Home (Online version only) |

# PalmNetServices.h

Go to the documentation of this file.

    00001 /******************************************************************************
    00002  * Copyright (c) 2004 palmOne, Inc. or its subsidiaries.
    00003  * All rights reserved.
    00004  *****************************************************************************/
    00005 /**
    00006  * @defgroup Network Network Library
    00007  *
    00008  * @{
    00009  * @}
    00010  */
    00011 /**
    00012  * @ingroup Network
    00013  */
    00014
    00015 /**
    00016  * @file    PalmNetServices.h
    00017  * @version 1.0
    00018  *
    00019  * @brief NetServices provides a set of API to access 802.11.
    00020  *
    00021  */
    00022
    00023 #ifndef PALM_NETSERVICES_H__
    00024 #define PALM_NETSERVICES_H__
    00025
    00026 #ifdef __MC68K__
    00027 #include <LibTraps.h>
    00028 #endif
    00029
    00030
    00031 /********************************************************************
    00032  * Traps
    00033  ********************************************************************/
    00034
    00035 /**
    00036  * @name Function Trap Numbers
    00037  */
    00038 /*@{*/
    00039 #define NetServicesLibTrapGetHWAddr         (sysLibTrapCustom+0)
    00040 #define NetServicesLibTrapStartScan         (sysLibTrapCustom+1)
    00041 #define NetServicesLibTrapGetScanResults    (sysLibTrapCustom+2)
    00042 #define NetServicesLibTrapGetChannel        (sysLibTrapCustom+3)
    00043 #define NetServicesLibTrapGetPowerState     (sysLibTrapCustom+4)
    00044 #define NetServicesLibTrapGetCommsQuality   (sysLibTrapCustom+5)
    00045 #define NetServicesLibTrapSetRadioState     (sysLibTrapCustom+6)
    00046 #define NetServicesLibTrapGetRadioState     (sysLibTrapCustom+7)
    00047 #define NetServicesLibTrapGetDeviceInfo     (sysLibTrapCustom+10)
    00048 #define NetServicesLibTrapGetChannelList    (sysLibTrapCustom+11)
    00049
    00050 #define NetServicesLibTrapProfileGetInfo    (sysLibTrapCustom+0x10)
    00051 #define NetServicesLibTrapProfileRead       (sysLibTrapCustom+0x11)
    00052 #define NetServicesLibTrapProfileWrite      (sysLibTrapCustom+0x12)
    00053 #define NetServicesLibTrapProfileAdd        (sysLibTrapCustom+0x13)
    00054 #define NetServicesLibTrapProfileDelete     (sysLibTrapCustom+0x14)
    00055 #define NetServicesLibTrapProfileSetOrder   (sysLibTrapCustom+0x15)
    00056 #define NetServicesLibTrapProfileGetOrder   (sysLibTrapCustom+0x16)
    00057 #define NetServicesLibTrapProfileFind       (sysLibTrapCustom+0x17)
    00058
    00059
    00060 /*@}*/
    00061
    00062 /********************************************************************
    00063  * Library type and creator
    00064  ********************************************************************/
    00065
    00066 #define ShlLibName      "NetServLib"    /**< PalmNetServices library name. */
    00067 #define ShlCreatorID    'NETs'          /**< PalmNetServices creator ID. */
    00068 #define ShlLibType      'libr'          /**< PalmNetServices library type. */
    00069
    00070
    00071 /********************************************************************
    00072  * Typedefs and constants for the device information returned from
    00073  * NetServicesGetDeviceInfo.
    00074  ********************************************************************/
    00075
    00076 #define kNetDriverDateLength    16      /**< Length for the driver date info string. */
    00077 #define kNetFWNameLength        16      /**< Length for the firmware name info string. */
    00078 #define kNetSerialNumberLength  16      /**< Length for the serial number info string. */
    00079
    00080 /**
    00081  * @brief Device information concerning Hardware and Firmware information for the "adapter".
    00082  *
    00083  * Revision information and product name data is returned.
    00084  */
    00085 typedef struct Net80211DeviceInfo
    00086 {
    00087     UInt32      validFlags;                             /**< Bit flag indicating validity of fields. */
    00088     UInt32      fwRev[2];                               /**< Firmware revision. STA/BB (32 bits), PRI/MAC (32 bits). Valid is (validFlags & 1) == 1.*/
    00089     Int32       serialNumberSize;                       /**< Serial number size. Valid is (validFlags & 8) == 1. */
    00090     UInt8       serialNumber[kNetSerialNumberLength];   /**< Serial number. Valid is (validFlags & 8) == 1. */
    00091     Char        driverDate[kNetDriverDateLength];       /**< Driver date. Valid is (validFlags & 2) == 1. */
    00092     Char        fwName[kNetFWNameLength];               /**< Firmware name. Valid is (validFlags & 4) == 1. */
    00093 } Net80211DeviceInfo, *Net80211DeviceInfoP;
    00094
    00095
    00096 /**
    00097  * @brief Data returned from NetServicesProfileGetInfo.
    00098  */
    00099 typedef struct NetServicesProfileInfo
    00100 {
    00101     UInt16  profileRev;         /**< Revision of profile database. */
    00102     UInt16  numProfiles;        /**< Number of profiles contained in the database. */
    00103     UInt16  profileEntrySize;   /**< Size of each individual profile entry. */
    00104 } NetServicesProfileInfo, *NetServicesProfileInfoP;
    00105
    00106 /**
    00107  * @brief Profile entries for SmartConnect
    00108  */
    00109 typedef struct NetServicesProfile
    00110 {
    00111     Char    profileName[32];    /**< ASCII string - profile reference. */
    00112     UInt8   SSID[32];           /**< SSID associated with this profile. */
    00113     UInt32  ssidLength;         /**< Length of bytes of the SSID. */
    00114     UInt16  ipAllocType;        /**< DHCP/STATIC/IPIPA. */
    00115     UInt16  preambleType;       /**< Long or short preamble. */
    00116     UInt16  keyIndex;           /**< WEP key index.  Only valid if wep active. */
    00117     UInt16  authentication;     /**< OPEN / 64 bit / 128 bit. */
    00118     UInt32  opMode;             /**< BSS, IBSS. */
    00119     UInt32  channel;            /**< DS Channel.  Only used for ad-hoc. */
    00120     UInt32  reqIP;              /**< Static IP address. */
    00121     UInt32  ipMask;             /**< IP mask. */
    00122     UInt32  ipGateway;          /**< IP gateway. */
    00123     UInt32  ipPrimaryDNS;       /**< IP primary DNS. */
    00124     UInt32  ipSecondaryDNS;     /**< IP secondary DNS. */
    00125     UInt8   wep[4][16];         /**< WEP keys. Up to 5 keys. */
    00126     UInt8   dhcpRequestDNS;     /**< 0 = DNS info static, 1 = DNS from DHCP. */
    00127 #ifdef WIFI_DOT1X_SUPPORT
    00128         UInt32  wppiCreator;            /**< Creator ID of Wi-Fi panel plugin (WPPI). */
    00129         UInt32  authenticationMethodID; /**< Identified authentication method to WPPI. */
    00130         UInt32  authenticationCookie;   /**< Identifies credentials to WPPI. */
    00131 #endif // WIFI_DOT1X_SUPPORT
    00132 } NetServicesProfile, *NetServicesProfileP;
    00133
    00134 /**
    00135  * @brief Profile entries version 1
    00136  */
    00137 typedef struct NetServicesProfileV1
    00138 {
    00139     Char    profileName[32];    /**< ASCII string - profile reference. */
    00140     UInt8   SSID[32];           /**< SSID associated with this profile. */
    00141     UInt32  ssidLength;         /**< Length of bytes of the SSID. */
    00142     UInt16  ipAllocType;        /**< DHCP/STATIC/IPIPA. */
    00143     UInt16  preambleType;       /**< Long or short preamble. */
    00144     UInt16  keyIndex;           /**< WEP key index.  Only valid if wep active. */
    00145     UInt16  authentication;     /**< OPEN / 64 bit / 128 bit. */
    00146     UInt32  opMode;             /**< BSS, IBSS. */
    00147     UInt32  channel;            /**< DS Channel.  Only used for ad-hoc. */
    00148     UInt32  reqIP;              /**< Static IP address. */
    00149     UInt32  ipMask;             /**< IP mask. */
    00150     UInt32  ipGateway;          /**< IP gateway. */
    00151     UInt32  ipPrimaryDNS;       /**< IP primary DNS. */
    00152     UInt32  ipSecondaryDNS;     /**< IP secondary DNS. */
    00153     UInt8   wep[4][16];         /**< WEP keys. Up to 5 keys. */
    00154     UInt8   dhcpRequestDNS;     /**< 0 = DNS info static, 1 = DNS from DHCP. */
    00155 } NetServicesProfileV1, *NetServicesProfileV1P;
    00156
    00157
    00158
    00159 /********************************************************************
    00160  * Priority order information
    00161  ********************************************************************/
    00162
    00163 #define MAX_ACTIVE_PROFILES     32      /**< Maximum number of profiles. */
    00164 #define END_OF_LIST             0xFFFF  /**< End of list marker. */
    00165 #define PRIORITY_LIST_SIZE      (sizeof(UInt16) * (MAX_ACTIVE_PROFILES + 1)) /**< Priority list size. */
    00166 #define INVALID_INDEX           0xFFFF  /**< Invalid index tag. */
    00167
    00168 /**
    00169  * @brief Priority order to smart connect.
    00170  *
    00171  * Provided for ease of reference.
    00172  */
    00173 typedef struct NetServicesProfileOrder
    00174 {
    00175     UInt16  order[MAX_ACTIVE_PROFILES+1];   /**< Array of order for each active profiles. */
    00176 } NetServicesProfileOrder, *NetServicesProfileOrderP;
    00177
    00178 /********************************************************************
    00179  * Prototypes
    00180  ********************************************************************/
    00181 #ifdef __cplusplus
    00182 extern "C" {
    00183 #endif
    00184
    00185 #ifdef __MC68K__
    00186 /**
    00187  * Gets the HW address (i.e. MAC address) for the interface
    00188  *
    00189  * @param   libRefNum:  IN:  Reference number of the library.
    00190  * @param   hwAddrP:    OUT: Pointer to store MAC address in.
    00191  *                           Must be 6 bytes in length.
    00192  *
    00193  * @retval  Err         Error code.
    00194  */
    00195 Err NetServicesGetHWAddr( UInt16 libRefNum, UInt8 *hwAddrP )
    00196                 SYS_TRAP(NetServicesLibTrapGetHWAddr);
    00197
    00198 /**
    00199  * Inititate a BSS scan.
    00200  * The scan completes by broadcasting a notification of
    00201  * type WIFI_SCAN_COMPLETE_EVENT.
    00202  *
    00203  * @param   libRefNum:  IN: Reference number of the library.
    00204  *
    00205  * @retval  Err         Error code.
    00206  */
    00207 Err NetServicesStartScan( UInt16 libRefNum )
    00208                 SYS_TRAP(NetServicesLibTrapStartScan);
    00209
    00210 /**
    00211  * Retreives scan results from a recent request for a  BSS scan.
    00212  * The caller can determine the amount of data available by passing
    00213  * a NULL pointer and a zero size for the buffer. The network device
    00214  * driver will return the space required to store the result.
    00215  *
    00216  * @param   libRefNum:      IN:  Reference number of the library.
    00217  * @param   scanResultsP:   OUT: Pointer to storage area which will
    00218  *                               hold the BSS scan data.
    00219  * @param   scanBufSizeP:   OUT: Pointer to variable which holds the
    00220  *                               size of the buffer.  Also used as
    00221  *                               output to determine size of results.
    00222  *
    00223  * @retval  Err             Error code.
    00224  */
    00225 Err NetServicesGetScanResults( UInt16 libRefNum, UInt8 *scanResultsP, UInt32 *scanBufSizeP )
    00226                 SYS_TRAP(NetServicesLibTrapGetScanResults);
    00227
    00228 /**
    00229  * Retreives the current channel number being used by the adapter.
    00230  * The exact method to get this data is determined by the adapter driver.
    00231  *
    00232  * @param   libRefNum:  IN:  Reference number of the library.
    00233  * @param   channelP    OUT: Pointer to storage area to store current
    00234  *                           channel number.
    00235  *
    00236  * @retval  Err         Error code.
    00237  */
    00238 Err NetServicesGetChannel( UInt16 libRefNum, UInt16 *channelP )
    00239                 SYS_TRAP(NetServicesLibTrapGetChannel);
    00240
    00241 /**
    00242  * Retreives the current mode (i.e. DSS, Freq. Hop) being  used
    00243  * by the adapter.  The exact method to get this data is determined
    00244  * by the adapter driver.
    00245  *
    00246  * @param   libRefNum:  IN:  Reference number of the library.
    00247  * @param   stateP:     OUT: Pointer to storage area to store current mode.
    00248  *
    00249  * @retval  Err         Error code.
    00250  */
    00251 Err NetServicesGetPowerState( UInt16 libRefNum, UInt16 *stateP )
    00252                 SYS_TRAP(NetServicesLibTrapGetPowerState);
    00253
    00254 /**
    00255  * Retreives the comms quality from the driver / firmware.
    00256  * The comms quality is the signal strength and quality.
    00257  *
    00258  * @param   libRefNum:  IN:  Reference number of the library.
    00259  * @param   strengthP:  OUT: Pointer to storage area to store signal strength.
    00260  * @param   qualityP:   OUT: Pointer to storage area for signal quality.
    00261  *
    00262  * @retval  Err         Error code.
    00263  */
    00264 Err NetServicesGetCommsQuality( UInt16 libRefNum, UInt8 *strengthP, UInt8 *qualityP )
    00265                 SYS_TRAP(NetServicesLibTrapGetCommsQuality);
    00266
    00267 /**
    00268  * Enables/disable the radio at the driver.
    00269  *
    00270  * @param   libRefNum:  IN: Reference number of the library.
    00271  * @param   radioState: IN: Boolean value indicating on/off.
    00272  *
    00273  * @retval  Err         Error code.
    00274  */
    00275 Err NetServicesSetRadioState( UInt16 libRefNum, UInt32 radioState )
    00276                 SYS_TRAP(NetServicesLibTrapSetRadioState);
    00277
    00278 /**
    00279  * Returns current status of the radio (0 = disabled, 1 = enabled).
    00280  *
    00281  * @param   libRefNum:      IN:  Reference number of the library.
    00282  * @param   radioStateP:    OUT: Pointer to storage area for the radio status.
    00283  *
    00284  * @retval  Err             Error code.
    00285  */
    00286 Err NetServicesGetRadioState( UInt16 libRefNum, UInt32 *radioStateP )
    00287                 SYS_TRAP(NetServicesLibTrapGetRadioState);
    00288
    00289
    00290 /**
    00291  * Queries the Firmware on the 802.11 chipset for revision and status info.
    00292  *
    00293  * @param   libRefNum:  IN:  Reference number of the library.
    00294  * @param   infoP:      OUT: Pointer to storage area for the firmware info.
    00295  *
    00296  * @retval  Err         Error code.
    00297  */
    00298 Err NetServicesGetDeviceInfo( UInt16 libRefNum, Net80211DeviceInfoP infoP )
    00299                 SYS_TRAP(NetServicesLibTrapGetDeviceInfo);
    00300
    00301 /**
    00302  * Retrieves the allowed channel list from the device driver.
    00303  * Used for regulatory domain control.  The channel list is a 16 bit,
    00304  * bit significant field with each bit indicating the channel + 1
    00305  * (i.e. bit 0 = CHN1).
    00306  *
    00307  * @param   libRefNum:      IN:  Reference number of the library.
    00308  * @param   channelListP:   OUT: Pointer to storage area for the channel list.
    00309  *
    00310  * @retval  Err             Error code.
    00311  */
    00312 Err NetServicesGetChannelList( UInt16 libRefNum, UInt16 *channelListP )
    00313                 SYS_TRAP(NetServicesLibTrapGetChannelList);
    00314
    00315 /**
    00316  * Provides information about the current profile database and profile manager.
    00317  *
    00318  * @param   libRefNum:  IN:  Reference number of the library.
    00319  * @param   infoP:      OUT: Pointer to storage area where the info will be stored.
    00320  *
    00321  * @retval  Err         Error code.
    00322  */
    00323 Err NetServicesProfileGetInfo( UInt16 libRefNum, NetServicesProfileInfoP infoP )
    00324                 SYS_TRAP(NetServicesLibTrapProfileGetInfo);
    00325
    00326 /**
    00327  * Reads the specified record from the database.  The index is verified
    00328  * first and then the data read into the user space.
    00329  *
    00330  * @param   libRefNum:  IN:  Reference number of the library.
    00331  * @param   profIndex:  IN:  Profile index number.
    00332  * @param   profileP:   OUT: Pointer to area where the profile will be read.
    00333  *
    00334  * @retval  Err         Error code.
    00335  */
    00336 Err NetServicesProfileRead( UInt16 libRefNum, UInt16 profIndex, NetServicesProfileP profileP )
    00337                 SYS_TRAP(NetServicesLibTrapProfileRead);
    00338
    00339 /**
    00340  * Updates the content of the specified record.
    00341  *
    00342  * @param   libRefNum:  IN: Reference number of the library.
    00343  * @param   profIndex:  IN: Record index number.
    00344  * @param   profileP:   IN: Pointer to profile data to be written to the database.
    00345  *
    00346  * @retval  Err         Error code.
    00347  */
    00348 Err NetServicesProfileWrite( UInt16 libRefNum, UInt16 profIndex, NetServicesProfileP profileP )
    00349                 SYS_TRAP(NetServicesLibTrapProfileWrite);
    00350
    00351 /**
    00352  * Deletes/removes the specified record from the database.
    00353  *
    00354  * @param   libRefNum:  IN: Reference number of the library.
    00355  * @param   profIndex:  IN: Profile index number.
    00356  *
    00357  * @retval  Err         Error code.
    00358  */
    00359 Err NetServicesProfileDelete( UInt16 libRefNum, UInt16 profIndex )
    00360                 SYS_TRAP(NetServicesLibTrapProfileDelete);
    00361
    00362 /**
    00363  * Adds a new record to the end of the profiles database.
    00364  *
    00365  * @param   libRefNum:  IN: Reference number of the library.
    00366  * @param   profileP:   IN: Pointer to new profile entry.
    00367  *
    00368  * @retval  Err         Error code.
    00369  */
    00370 Err NetServicesProfileAdd( UInt16 libRefNum, NetServicesProfileP profileP )
    00371                 SYS_TRAP(NetServicesLibTrapProfileAdd);
    00372
    00373 /**
    00374  * Requests to update the priority order of the profiles.
    00375  * The routine verifies all the profile entries exist and
    00376  * then updates the profile header with the info.
    00377  *
    00378  * @param   libRefNum:  IN: Reference number of the library.
    00379  * @param   orderP:     IN: Pointer to new priority list.
    00380  *                          Must be terminated by END_OF_LIST (0xFFFF).
    00381  *
    00382  * @retval  Err         Error code.
    00383  */
    00384 Err NetServicesProfileSetOrder( UInt16 libRefNum, NetServicesProfileOrderP orderP )
    00385                 SYS_TRAP(NetServicesLibTrapProfileSetOrder);
    00386
    00387 /**
    00388  * Requests to retreive the current priority order to the SmartConnect.
    00389  *
    00390  * @param   libRefNum:  IN: Reference number of the library.
    00391  * @param   orderP:     OUT: Pointer to storage area where the list will be stored.
    00392  *
    00393  * @retval  Err         Error code.
    00394  */
    00395 Err NetServicesProfileGetOrder( UInt16 libRefNum, NetServicesProfileOrderP orderP )
    00396                 SYS_TRAP(NetServicesLibTrapProfileGetOrder);
    00397
    00398 /**
    00399  * Searches through the records in the database for the specified
    00400  * profile name.  If the profile exists, the index is returned to
    00401  * the caller. A value of INVALID_INDEX indicates the profile was not found.
    00402  *
    00403  * @param   libRefNum:  IN:  Reference number of the library.
    00404  * @param   profNameP:  OUT: Pointer to storage area where the list will be stored.
    00405  *
    00406  * @retval  Err         Error code.
    00407  */
    00408 Err NetServicesProfileFind( UInt16 libRefNum, Char *profNameP )
    00409                 SYS_TRAP(NetServicesLibTrapProfileFind);
    00410
    00411
    00412 #else   // __MC68K__
    00413 Err NetServicesGetHWAddr( UInt16 refnum, UInt8 *hwAddrP );
    00414 Err NetServicesStartScan( UInt16 refnum );
    00415 Err NetServicesGetScanResults( UInt16 refnum, UInt8 *scanResultsP, UInt32 *scanBufSizeP );
    00416 Err NetServicesGetChannel( UInt16 refnum, UInt16 *channelP );
    00417 Err NetServicesGetPowerState( UInt16 refnum, UInt16 *modeP );
    00418 Err NetServicesGetCommsQuality( UInt16 refNum, UInt8 *strengthP, UInt8 *qualityP );
    00419 Err NetServicesSetRadioState( UInt16 refNum, UInt32 enable );
    00420 Err NetServicesGetRadioState( UInt16 libRef, UInt32 *radioStateP );
    00421 Err NetServicesGetDeviceInfo( UInt16 refNum, Net80211DeviceInfoP storageP );
    00422 Err NetServicesGetChannelList( UInt16 refNum, UInt16 *channelP );
    00423
    00424 Err NetServicesProfileGetInfo( UInt16 libRef, NetServicesProfileInfoP infoP );
    00425 Err NetServicesProfileRead( UInt16 libRef, UInt16 profIndex, NetServicesProfileP profileP );
    00426 Err NetServicesProfileWrite( UInt16 libRef, UInt16 profIndex, NetServicesProfileP profileP );
    00427 Err NetServicesProfileDelete( UInt16 libRef, UInt16 profIndex );
    00428 Err NetServicesProfileAdd( UInt16 libRef, NetServicesProfileP profileP );
    00429 Err NetServicesProfileSetOrder( UInt16 libRef, NetServicesProfileOrderP orderP );
    00430 Err NetServicesProfileGetOrder( UInt16 libRef, NetServicesProfileOrderP orderP );
    00431 UInt16 NetServicesProfileFind( UInt16 libRef, Char *profNameP );
    00432
    00433
    00434 #endif  // __MC68K__
    00435
    00436 #ifdef __cplusplus
    00437 }
    00438 #endif
    00439
    00440 #endif // PALM_NETSERVICES_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