src/windows/identity/uilib/khprops.h

   1 /*\r
   2  * Copyright (c) 2004 Massachusetts Institute of Technology\r
   3  *\r
   4  * Permission is hereby granted, free of charge, to any person\r
   5  * obtaining a copy of this software and associated documentation\r
   6  * files (the "Software"), to deal in the Software without\r
   7  * restriction, including without limitation the rights to use, copy,\r
   8  * modify, merge, publish, distribute, sublicense, and/or sell copies\r
   9  * of the Software, and to permit persons to whom the Software is\r
  10  * furnished to do so, subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be\r
  13  * included in all copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,\r
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\r
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND\r
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS\r
  19  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN\r
  20  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r
  22  * SOFTWARE.\r
  23  */\r
  24 \r
  25 /* $Id$ */\r
  26 \r
  27 #ifndef __KHIMAIRA_KHPROPS_H\r
  28 #define __KHIMAIRA_KHPROPS_H\r
  29 \r
  30 /*********************************************************************\r
  31   Property sheets\r
  32 **********************************************************************/\r
  33 \r
  34 /*! \addtogroup khui \r
  35 \r
  36 @{*/\r
  37 \r
  38 /*!\defgroup khui_pp Property sheets\r
  39 @{*/\r
  40 \r
  41 /* forward dcl */\r
  42 struct tag_khui_property_page;\r
  43 \r
  44 /*! \brief A property sheet\r
  45  */\r
  46 typedef struct tag_khui_property_sheet {\r
  47   PROPSHEETHEADER header;    /*!< property sheet header */\r
  48   khm_int32       status;    /*!< status of property sheet.  One of\r
  49                                ::KHUI_PS_STATUS_NONE,\r
  50                                ::KHUI_PS_STATUS_RUNNING or\r
  51                                ::KHUI_PS_STATUS_DONE */\r
  52 \r
  53   HWND            hwnd;      /*!< handle to the property sheet window.\r
  54                                Only valid when \a status is NOT\r
  55                                ::KHUI_PS_STATUS_NONE */\r
  56 \r
  57   HWND            hwnd_page; /*!< handle to the current page in the\r
  58                                property sheet.  Only valid when \a\r
  59                                status is ::KHUI_PS_STATUS_RUNNING */\r
  60 \r
  61   khui_action_context ctx;   /*!< Context for the property sheet.  See\r
  62                                documentation for\r
  63                                ::khui_action_context */\r
  64 \r
  65   khm_handle      identity;  /*!< Handle to the associated identity,\r
  66                                if applicable */\r
  67   khm_int32       credtype;  /*!< Type ID of the credentials type, if\r
  68                                applicable */\r
  69   khm_handle      cred;      /*!< Handle to the associated credential,\r
  70                                if applicable */\r
  71 \r
  72   khm_int32       n_pages;   /*!< Number of property pages.\r
  73                                Upperbound of ::KHUI_PS_MAX_PSP */\r
  74 \r
  75   QDCL(struct tag_khui_property_page);\r
  76 } khui_property_sheet;\r
  77 \r
  78 /*! \brief The property sheet hasn't been created yet */\r
  79 #define KHUI_PS_STATUS_NONE 0\r
  80 \r
  81 /*! \brief The property sheet is visible and running */\r
  82 #define KHUI_PS_STATUS_RUNNING 1\r
  83 \r
  84 /*! \brief The property sheet has completed running.\r
  85 \r
  86     At this point, it is safe to call khui_ps_destroy_sheet() to\r
  87     destroy the property sheet.\r
  88 */\r
  89 #define KHUI_PS_STATUS_DONE 2\r
  90 \r
  91 /*! \brief The property sheet is in the process of being destroyed\r
  92  */\r
  93 #define KHUI_PS_STATUS_DESTROY 3\r
  94 \r
  95 /*! \brief Maximum number of property sheet pages in a property sheet */\r
  96 #define KHUI_PS_MAX_PSP 16\r
  97 \r
  98 \r
  99 /*! \brief A property sheet page\r
 100  */\r
 101 typedef struct tag_khui_property_page {\r
 102   HPROPSHEETPAGE h_page;\r
 103   LPPROPSHEETPAGE p_page;\r
 104   HWND           hwnd;\r
 105   khm_int32      credtype;\r
 106   khm_int32      ordinal;\r
 107 \r
 108   LDCL(struct tag_khui_property_page);\r
 109 } khui_property_page;\r
 110 \r
 111 /*! \brief Special pseudo credtype for identity page\r
 112  */\r
 113 #define KHUI_PPCT_IDENTITY (-8)\r
 114 \r
 115 /*! \brief Special pseudo credtype for credential page\r
 116  */\r
 117 #define KHUI_PPCT_CREDENTIAL (-9)\r
 118 \r
 119 /*! \brief Create a property sheet\r
 120 \r
 121     \note Only called by the NetIDMgr application.\r
 122  */\r
 123 KHMEXP khm_int32 KHMAPI \r
 124 khui_ps_create_sheet(khui_property_sheet ** sheet);\r
 125 \r
 126 /*! \brief Add a page to a property sheet\r
 127 \r
 128     Called by a plugin or the NetIDMgr application to add a page to a\r
 129     property sheet.\r
 130 \r
 131     Pages can only be added before the property sheet is made visible\r
 132     to the user.\r
 133 \r
 134     \param[in] sheet The property sheet to add the page to\r
 135 \r
 136     \param[in] credtype The credentials type ID of the owner of the\r
 137         property page.  This should be set to ::KCDB_CREDTYPE_INVALID\r
 138         if the type is not relevant.\r
 139 \r
 140     \param[in] ordinal Requested ordinal.  A positive integer which is\r
 141         used to order the pages in a property sheet.  The pages are\r
 142         ordered based on ordinal first and then alphabetically by\r
 143         credentials type name.  If the type is unavailable, then the\r
 144         ordering is undefined.\r
 145 \r
 146     \param[in] ppage Pointer to structure that will be passed to\r
 147         CreatePropertySheetPage() to create the property page.  The\r
 148         structure is not managed by NetIDMgr at all, and must exist\r
 149         until the status of the property sheet changes to\r
 150         ::KHUI_PS_STATUS_RUNNING.  The same pointer will be found in\r
 151         the \a p_page member of the ::khui_property_page structure.\r
 152 \r
 153     \param[out] page A pointer will be returned here that will point\r
 154         to the newly created khui_property_page structure.  Specify\r
 155         NULL if this value is not required.  You can use\r
 156         khui_ps_find_page() to retrieve a pointer to the structure\r
 157         later.\r
 158  */\r
 159 KHMEXP khm_int32 KHMAPI \r
 160 khui_ps_add_page(khui_property_sheet * sheet,\r
 161                  khm_int32 credtype,\r
 162                  khm_int32 ordinal,\r
 163                  LPPROPSHEETPAGE ppage,\r
 164                  khui_property_page ** page);\r
 165 \r
 166 /*! \brief Retrieve a property page structure from a property sheet\r
 167  */\r
 168 KHMEXP khm_int32 KHMAPI\r
 169 khui_ps_find_page(khui_property_sheet * sheet,\r
 170                   khm_int32 credtype,\r
 171                   khui_property_page ** page);\r
 172 \r
 173 /*! \brief Display the property sheet\r
 174 \r
 175     \note Only called by the NetIDMgr application\r
 176  */\r
 177 KHMEXP HWND KHMAPI \r
 178 khui_ps_show_sheet(HWND parent, \r
 179                    khui_property_sheet * sheet);\r
 180 \r
 181 /*! \brief Check if the given message belongs to the property sheet\r
 182 \r
 183     \note Only called by the NetIDMgr application\r
 184  */\r
 185 KHMEXP LRESULT KHMAPI \r
 186 khui_ps_check_message(khui_property_sheet * sheet, \r
 187                       PMSG msg);\r
 188 \r
 189 /*! \brief Destroy a property sheet and all associated data structures.\r
 190 \r
 191     \note Only called by the NetIDMgr application.\r
 192 */\r
 193 KHMEXP khm_int32 KHMAPI \r
 194 khui_ps_destroy_sheet(khui_property_sheet * sheet);\r
 195 \r
 196 KHMEXP khm_int32 KHMAPI \r
 197 khui_property_wnd_set_record(HWND hwnd_pwnd, khm_handle record);\r
 198 \r
 199 /*!@}*/\r
 200 /*!@}*/\r
 201 \r
 202 #endif\r