API Guide Home (Online version only) |

# PalmWPPI.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  * @ingroup Network
    00007  */
    00008
    00009 /**
    00010  * @file    PalmWPPI.h
    00011  * @version 1.0
    00012  * @date    05/16/2003
    00013  *
    00014  * @brief This is the API for Wi-Fi panel plug-ins (WPPIs).
    00015  *
    00016  * The Wi-Fi panel allows the user to manage their network profiles. Each profile includes a
    00017  * plugin, an authentication method, and a cookie used to identify the
    00018  * user's credentials. Each plugin provides support for one or more
    00019  * authentication methods; e.g., LEAP, PEAP, etc. A WPPI provides access to
    00020  * the user interface of an 802.1x client.
    00021  *
    00022  */
    00023
    00024 #ifndef _PALM_WPPI_H_
    00025 #define _PALM_WPPI_H_
    00026
    00027
    00028 // A WPPI is much like an application. It has a PilotMain function that responds
    00029 // to certain launch codes. Applications are databases of type 'appl'. WPPIs use
    00030 // this type instead:
    00031
    00032 #define sysFileTWiFiPanelPlugin     'Wppi'  /**< database type for Wi-Fi panel plug-ins */
    00033
    00034 // The creator ID of the database should be registered as usual. WPPI's don't have
    00035 // user-visible names; only authentication methods are visible to the user. A WPPI
    00036 // will typically have form resources, etc. These can be in the normal sub-10000 range
    00037 // reserved for application.
    00038
    00039 // A WPPI is always is always sublaunched, so it never has access to global variables
    00040 // or multiple code segments. The value returned by the PilotMain function is always
    00041 // ignored. Instead, an err field in the command parameter block is used to indicate
    00042 // success or failure. This is only used for out-of-memory and stuff like that, not
    00043 // for user-cancel. The Wi-Fi panel sets the err field to a non-zero value before
    00044 // calling the WPPI. The WPPI is responsible for zeroing the err field before returning
    00045 // if it's successful. The error code used doesn't matter; it is only used to indicate
    00046 // success or failure.
    00047
    00048 // Each WPPI is responsible for storing the credentials associated with accounts that
    00049 // use its authentication methods.
    00050
    00051 // The Wi-Fi panel queries each WPPI for a list of authentication methods and then
    00052 // merges the results. The query uses the following launch code and command parameter
    00053 // block:
    00054
    00055 #define sysWPPILaunchCmdGetAuthenticationMethods        sysAppLaunchCmdCustomBase   // 0x8000
    00056
    00057 #define kMaxWiFiAuthenticationMethodNameLength          31
    00058
    00059 typedef struct
    00060     {
    00061     UInt32  wppiCreator; /**< the creator ID of the WPPI that provides the authentication method */
    00062     UInt32  authenticationMethodID; /**< an arbitrary 32-bit ID used by the WPPI to identify the authentication method */
    00063     Char    authenticationMethodName[kMaxWiFiAuthenticationMethodNameLength + 1]; /**< the user-visible name for the authentication method (max width is 50 pixels) */
    00064     } WiFiAuthenticationMethodType;
    00065
    00066 typedef struct
    00067     {
    00068     UInt32                        numAuthenticationMethods;
    00069     WiFiAuthenticationMethodType* authenticationMethods;
    00070     Err                           err;
    00071     } SysWPPILaunchCmdGetAuthenticationMethodsType;
    00072
    00073 // The Wi-Fi panel will zero numAuthenticationMethods and authenticationMethods before
    00074 // calling the WPPI. It should allocate a chunk in the dynamic heap to store the
    00075 // authentication methods and put a pointer to this chunk in the authenticationMethods
    00076 // field. The Wi-Fi panel will free this chunk. Note that the WPPI creator ID is
    00077 // duplicated in each account.
    00078
    00079 // A WPPI is expected to maintain a database of credentials for each network that uses
    00080 // one of its authentication methods. The records in this database are identified by
    00081 // their unique ID. The Wi-Fi panel saves this unique ID, or cookie, along with all the
    00082 // other network settings, in its own database. A value of zero is used to indicate
    00083 // that there are no credentials because this is a new network or because the user
    00084 // switched authentication methods. The WPPI shouldn't save the user's credentials into
    00085 // its database until the Wi-Fi panel tells it to. This happens when the user taps the
    00086 // OK button in the Edit Network dialog. Until then, the entered credentials should be
    00087 // saved in a temporary location such as one or more features.
    00088
    00089 // The Wi-Fi panel makes the following sequence of calls into the WPPI:
    00090 // - sysWPPILaunchCmdOpen
    00091 // - sysWPPILaunchCmdDialog (zero or more times)
    00092 // - sysWPPILaunchCmdClose
    00093 // When the Edit Network dialog opens, the Wi-Fi panel calls sysWPPILaunchCmdOpen
    00094 // for the current WPPI and authentication method. When the user taps on the
    00095 // credentials selector trigger, the Wi-Fi panel calls sysWPPILaunchCmdDialog.
    00096 // When the user taps OK or Cancel in the Edit Network dialog, the Wi-Fi panel
    00097 // calls sysWPPILaunchCmdClose. If the user switches authentication methods, the
    00098 // Wi-Fi panel calls sysWPPILaunchCmdClose for the old method and
    00099 // sysWPPILaunchCmdOpen for the new one. All of these take the same command
    00100 // parameter block:
    00101
    00102 #define kMaxWiFiCredentialsLabelLength                      31  // excludes terminator
    00103 #define kMaxWiFiCredentialsSelectorTriggerLength        31  // excludes terminator
    00104
    00105 typedef struct
    00106     {
    00107     UInt32  authenticationMethodID; /**< a 32-bit ID used by the WPPI to identify the authentication method */
    00108     UInt32  cookie; /**< a unique ID or other identifier used to look up the credentials */
    00109     Boolean save; /**< whether to save the user's changes (only for sysWPPILaunchCmdClose) */
    00110     Boolean cancel; /**< whether the user tapped Cancel (only for sysWPPILaunchCmdDialog) */
    00111     Boolean assigned; /**< whether credentials are considered assigned for validation purposes */
    00112     Char    credentialsLabel[kMaxWiFiCredentialsLabelLength + 1]; /**< the label to use for the credentials line in the Edit Network dialog */
    00113     Char    credentialsSelectorTrigger[kMaxWiFiCredentialsSelectorTriggerLength + 1]; /**< the selector trigger label indicating whether credentials have been assigned */
    00114     Err     err; /**< non-zero on entry; set by WPPI to indicate success or failure */
    00115     } SysWPPILaunchCmdType;
    00116
    00117 #define sysWPPILaunchCmdOpen        sysAppLaunchCmdCustomBase + 1                    // 0x8001
    00118
    00119 /// If a non-zero cookie is passed in, we're editing an existing network with existing
    00120 /// credentials. The WPPI should find the credentials in its database and put them in
    00121 /// a temporary location. If a zero cookie is passed in, we're either creating a new
    00122 /// network, editing an existing network that didn't previous have credentials, or
    00123 /// switching authentication methods. The WPPI should set the credentialsLabel and
    00124 /// credentialsSelectorTrigger. Typically, the credentialsLabel is "Credentials:" and
    00125 /// the credentialsSelectorTrigger is "-Assigned-" or "-Unassigned-". Every call to
    00126 /// sysWPPILaunchCmdOpen is matched with a call to sysWPPILaunchCmdClose.
    00127
    00128 #define sysWPPILaunchCmdClose       sysAppLaunchCmdCustomBase + 2                    // 0x8002
    00129
    00130 /// If the save flag is set, the WPPI should write the user's credentials to its
    00131 /// database. If the cookie is zero, it should create a new record and save its
    00132 /// unique ID in the cookie field of the command parameter block. If the cookie is
    00133 /// non-zero, it should overwrite the old record.
    00134
    00135 #define sysWPPILaunchCmdDialog  sysAppLaunchCmdCustomBase + 3                    // 0x8003
    00136
    00137 /// The WPPI should open its dialog and allow the user to edit the credentials. It
    00138 /// should read from the temporary location to initialize the username and password
    00139 /// fields or other UI elements as appropriate. It should write to the temporary
    00140 /// location when the user taps OK. It shouldn't access its database. Whether the
    00141 /// user tapped Cancel should be stored in the cancel flag in the command parameter
    00142 /// block. If the user taps OK and this changes the current credentials state
    00143 /// (typically assigned/unassigned), the credentialsSelectorTrigger field should
    00144 /// be updated by the WPPI. Note that the user may delete his credentials causing
    00145 /// the state to change from assigned to unassigned.
    00146
    00147 #define sysWPPILaunchCmdDelete  sysAppLaunchCmdCustomBase + 4                    // 0x8004
    00148
    00149 /// When the user deletes a network, the Wi-Fi panel notifies the WPPI to delete
    00150 /// the corresponding credentials. This uses the same command parameter block as
    00151 /// above. The cookie field is used to indentify the record in the WPPI's
    00152 /// database. A zero value should be ignored. If the user switches authentication
    00153 /// methods and taps OK to save the edited network, the Wi-Fi panel notifies the
    00154 /// old WPPI to delete the old credentials.
    00155
    00156 /// Finally, the Wi-Fi Setup wizard displays a detailed description of the selected
    00157 /// authentication method. To do this, it sublaunches the WPPI with the following
    00158 /// launch code and command parameter block.
    00159
    00160 #define sysWPPILaunchCmdGetDescription      sysAppLaunchCmdCustomBase + 5           // 0x8005
    00161
    00162 typedef struct
    00163     {
    00164     UInt32 authenticationMethodID;
    00165     Char*  description;
    00166     UInt32 descriptionSize;
    00167     Err    err;
    00168     } SysWPPILaunchCmdGetDescriptionType;
    00169
    00170 /// The WPPI should write into the description buffer supplied. The buffer is
    00171 /// allocated by the Wi-Fi panel. The WPPI should avoid writing past the end of
    00172 /// the buffer. The size of the buffer is included in the command parameter block.
    00173 /// The description is displayed in an 8 line, full width field in the normal
    00174 /// font.
    00175
    00176 ///
    00177 /// This is invoked to bring up the prompt dialog (WPPI decides if
    00178 /// prompt is necessary) or pass any kind of data to the WPPI.
    00179 /// Optionally, before exiting, a WPPI can set the
    00180 /// netIFSettingDot1XConfig setting to pass information back to the
    00181 /// 802.1X plugin.
    00182 ///
    00183 #define sysWPPILaunchCmdPromptAndConfigure      (sysAppLaunchCmdCustomBase + 6)   // 0x8006
    00184
    00185 typedef struct
    00186 {
    00187   UInt32   ifCreator;   // in
    00188   UInt32   ifInstance;  // in
    00189   Err      errOut;      // out
    00190 } SysWPPILaunchCmdPromptAndConfigureType;
    00191
    00192
    00193 ///
    00194 /// This is invoked to put up an error dialog.
    00195 ///
    00196 #define sysWPPILaunchCmdErrorDialog     (sysAppLaunchCmdCustomBase + 7)   // 0x8007
    00197
    00198 typedef struct
    00199 {
    00200   UInt32        error;          // in
    00201   Err           errOut;         // out
    00202 } SysWPPILaunchCmdErrorDialogType;
    00203
    00204 ///
    00205 /// This is invoked to request a password cache clear.
    00206 /// Removes temporary passwords from all accounts managed by the WPPI.
    00207 ///
    00208 #define sysWPPILaunchCmdClearPWCache    (sysAppLaunchCmdCustomBase + 8)   // 0x8008
    00209
    00210 typedef struct
    00211 {
    00212   Err           errOut;         // out
    00213 } SysWPPILaunchCmdClearPWCache;
    00214
    00215
    00216 #endif  //_PALM_WPPI_H_

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