source3/rpc_server/srv_spoolss_util.h

   1 /*
   2  *  Unix SMB/CIFS implementation.
   3  *
   4  *  SPOOLSS RPC Pipe server / winreg client routines
   5  *
   6  *  Copyright (c) 2010      Andreas Schneider <asn@samba.org>
   7  *
   8  *  This program is free software; you can redistribute it and/or modify
   9  *  it under the terms of the GNU General Public License as published by
  10  *  the Free Software Foundation; either version 3 of the License, or
  11  *  (at your option) any later version.
  12  *
  13  *  This program is distributed in the hope that it will be useful,
  14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  *  GNU General Public License for more details.
  17  *
  18  *  You should have received a copy of the GNU General Public License
  19  *  along with this program; if not, see <http://www.gnu.org/licenses/>.
  20  */
  21
  22 #ifndef _SRV_SPOOLSS_UITL_H
  23 #define _SRV_SPOOLSS_UITL_H
  24
  25 /**
  26  * @internal
  27  *
  28  * @brief Set printer data over the winreg pipe.
  29  *
  30  * @param[in]  mem_ctx  The talloc memory context to use.
  31  *
  32  * @param[in]  server_info The server supplied session info.
  33  *
  34  * @param[in]  printer  The printer name.
  35  *
  36  * @param[in]  key      The key of the printer data to store the value.
  37  *
  38  * @param[in]  value    The value name to save.
  39  *
  40  * @param[in]  type     The type of the value to use.
  41  *
  42  * @param[in]  data     The data which sould be saved under the given value.
  43  *
  44  * @param[in]  data_size The size of the data.
  45  *
  46  * @return              On success WERR_OK, a corresponding DOS error is
  47  *                      something went wrong.
  48  */
  49 WERROR winreg_set_printer_dataex(TALLOC_CTX *mem_ctx,
  50                                  struct auth_serversupplied_info *server_info,
  51                                  const char *printer,
  52                                  const char *key,
  53                                  const char *value,
  54                                  enum winreg_Type type,
  55                                  uint8_t *data,
  56                                  uint32_t data_size);
  57
  58 /**
  59  * @internal
  60  *
  61  * @brief Get printer data over a winreg pipe.
  62  *
  63  * @param[in]  mem_ctx  The talloc memory context to use.
  64  *
  65  * @param[in]  server_info The server supplied session info.
  66  *
  67  * @param[in]  printer  The printer name.
  68  *
  69  * @param[in]  key      The key of the printer data to get the value.
  70  *
  71  * @param[in]  value    The name of the value to query.
  72  *
  73  * @param[in]  type     The type of the value to query.
  74  *
  75  * @param[out] data     A pointer to store the data.
  76  *
  77  * @param[out] data_size A pointer to store the size of the data.
  78  *
  79  * @return              On success WERR_OK, a corresponding DOS error is
  80  *                      something went wrong.
  81  */
  82 WERROR winreg_get_printer_dataex(TALLOC_CTX *mem_ctx,
  83                                  struct auth_serversupplied_info *server_info,
  84                                  const char *printer,
  85                                  const char *key,
  86                                  const char *value,
  87                                  enum winreg_Type *type,
  88                                  uint8_t **data,
  89                                  uint32_t *data_size);
  90
  91 /**
  92  * @internal
  93  *
  94  * @brief Enumerate on the values of a given key and provide the data.
  95  *
  96  * @param[in]  mem_ctx  The talloc memory context to use.
  97  *
  98  * @param[in]  server_info The server supplied session info.
  99  *
 100  * @param[in]  printer  The printer name.
 101  *
 102  * @param[in]  key      The key of the printer data to get the value.
 103  *
 104  * @param[out] pnum_values A pointer to store the number of values we found.
 105  *
 106  * @param[out] penum_values A pointer to store the values and its data.
 107  *
 108  * @return                   WERR_OK on success, the corresponding DOS error
 109  *                           code if something gone wrong.
 110  */
 111 WERROR winreg_enum_printer_dataex(TALLOC_CTX *mem_ctx,
 112                                   struct auth_serversupplied_info *server_info,
 113                                   const char *printer,
 114                                   const char *key,
 115                                   uint32_t *pnum_values,
 116                                   struct spoolss_PrinterEnumValues **penum_values);
 117
 118 /**
 119  * @internal
 120  *
 121  * @brief Delete printer data over a winreg pipe.
 122  *
 123  * @param[in]  mem_ctx  The talloc memory context to use.
 124  *
 125  * @param[in]  server_info The server supplied session info.
 126  *
 127  * @param[in]  printer  The printer name.
 128  *
 129  * @param[in]  key      The key of the printer data to delete.
 130  *
 131  * @param[in]  value    The name of the value to delete.
 132  *
 133  * @return              On success WERR_OK, a corresponding DOS error is
 134  *                      something went wrong.
 135  */
 136 WERROR winreg_delete_printer_dataex(TALLOC_CTX *mem_ctx,
 137                                     struct auth_serversupplied_info *server_info,
 138                                     const char *printer,
 139                                     const char *key,
 140                                     const char *value);
 141
 142 /**
 143  * @internal
 144  *
 145  * @brief Enumerate on the subkeys of a given key and provide the data.
 146  *
 147  * @param[in]  mem_ctx  The talloc memory context to use.
 148  *
 149  * @param[in]  server_info The server supplied session info.
 150  *
 151  * @param[in]  printer  The printer name.
 152  *
 153  * @param[in]  key      The key of the printer data to get the value.
 154  *
 155  * @param[out] pnum_subkeys A pointer to store the number of subkeys found.
 156  *
 157  * @param[in]  psubkeys A pointer to an array to store the names of the subkeys
 158  *                      found.
 159  *
 160  * @return              WERR_OK on success, the corresponding DOS error
 161  *                      code if something gone wrong.
 162  */
 163 WERROR winreg_enum_printer_key(TALLOC_CTX *mem_ctx,
 164                                struct auth_serversupplied_info *server_info,
 165                                const char *printer,
 166                                const char *key,
 167                                uint32_t *pnum_subkeys,
 168                                const char ***psubkeys);
 169
 170 /**
 171  * @internal
 172  *
 173  * @brief Delete a key with subkeys of a given printer.
 174  *
 175  * @param[in]  mem_ctx  The talloc memory context to use.
 176  *
 177  * @param[in]  server_info The server supplied session info.
 178  *
 179  * @param[in]  printer  The printer name.
 180  *
 181  * @param[in]  key      The key of the printer to delete.
 182  *
 183  * @return              On success WERR_OK, a corresponding DOS error is
 184  *                      something went wrong.
 185  */
 186 WERROR winreg_delete_printer_key(TALLOC_CTX *mem_ctx,
 187                                  struct auth_serversupplied_info *server_info,
 188                                  const char *printer,
 189                                  const char *key);
 190
 191 /**
 192  * @brief Update the ChangeID of a printer.
 193  *
 194  * The ChangeID **must** be increasing over the lifetime of client's spoolss
 195  * service in order for the client's cache to show updates.
 196  *
 197  * If a form is updated of a printer, the we need to update the ChangeID of the
 198  * pritner.
 199  *
 200  * @param[in]  mem_ctx  The talloc memory context to use.
 201  *
 202  * @param[in]  server_info The server supplied session info.
 203  *
 204  * @param[in]  printer  The printer name.
 205  *
 206  * @return              On success WERR_OK, a corresponding DOS error is
 207  *                      something went wrong.
 208  */
 209 WERROR winreg_printer_update_changeid(TALLOC_CTX *mem_ctx,
 210                                       struct auth_serversupplied_info *server_info,
 211                                       const char *printer);
 212
 213 /**
 214  * @brief Get the ChangeID of the given printer.
 215  *
 216  * @param[in]  mem_ctx  The talloc memory context to use.
 217  *
 218  * @param[in]  server_info The server supplied session info.
 219  *
 220  * @param[in]  printer  The printer name.
 221  *
 222  * @param[in]  changeid A pointer to store the changeid.
 223  *
 224  * @return              On success WERR_OK, a corresponding DOS error is
 225  *                      something went wrong.
 226  */
 227 WERROR winreg_printer_get_changeid(TALLOC_CTX *mem_ctx,
 228                                    struct auth_serversupplied_info *server_info,
 229                                    const char *printer,
 230                                    uint32_t *pchangeid);
 231
 232 /**
 233  * @internal
 234  *
 235  * @brief This function adds a form to the list of available forms that can be
 236  * selected for the specified printer.
 237  *
 238  * @param[in]  mem_ctx  The talloc memory context to use.
 239  *
 240  * @param[in]  server_info The server supplied session info.
 241  *
 242  * @param[in]  form     The form to add.
 243  *
 244  * @return              WERR_OK on success.
 245  *                      WERR_ALREADY_EXISTS if the form already exists or is a
 246  *                                          builtin form.
 247  *                      A corresponding DOS error is something went wrong.
 248  */
 249 WERROR winreg_printer_addform1(TALLOC_CTX *mem_ctx,
 250                                struct auth_serversupplied_info *server_info,
 251                                struct spoolss_AddFormInfo1 *form);
 252
 253 /*
 254  * @brief This function enumerates the forms supported by the specified printer.
 255  *
 256  * @param[in]  mem_ctx  The talloc memory context to use.
 257  *
 258  * @param[in]  server_info The server supplied session info.
 259  *
 260  * @param[out] pnum_info A pointer to store the FormInfo count.
 261  *
 262  * @param[out] pinfo     A pointer to store an array with FormInfo.
 263  *
 264  * @return              On success WERR_OK, a corresponding DOS error is
 265  *                      something went wrong.
 266  */
 267 WERROR winreg_printer_enumforms1(TALLOC_CTX *mem_ctx,
 268                                  struct auth_serversupplied_info *server_info,
 269                                  uint32_t *pnum_info,
 270                                  union spoolss_FormInfo **pinfo);
 271
 272 /**
 273  * @brief This function removes a form name from the list of supported forms.
 274  *
 275  * @param[in]  mem_ctx  The talloc memory context to use.
 276  *
 277  * @param[in]  server_info The server supplied session info.
 278  *
 279  * @param[in]  form_name The name of the form to delete.
 280  *
 281  * @return              WERR_OK on success.
 282  *                      WERR_INVALID_PARAM if the form is a builtin form.
 283  *                      WERR_INVALID_FORM_NAME if the form or key doesn't exist.
 284  *                      A corresponding DOS error is something went wrong.
 285  */
 286 WERROR winreg_printer_deleteform1(TALLOC_CTX *mem_ctx,
 287                                   struct auth_serversupplied_info *server_info,
 288                                   const char *form_name);
 289
 290 /**
 291  * @brief This function sets the form information for the specified printer.
 292  *
 293  * If one provides both the name in the API call and inside the FormInfo
 294  * structure, then the form gets renamed.
 295  *
 296  * @param[in]  mem_ctx  The talloc memory context to use.
 297  *
 298  * @param[in]  server_info The server supplied session info.
 299  *
 300  * @param[in]  form_name The name of the form to set or rename.
 301  *
 302  * @param[in]  form     The FormInfo structure to save.
 303  *
 304  * @return              WERR_OK on success.
 305  *                      WERR_INVALID_PARAM if the form is a builtin form.
 306  *                      A corresponding DOS error is something went wrong.
 307  */
 308 WERROR winreg_printer_setform1(TALLOC_CTX *mem_ctx,
 309                                struct auth_serversupplied_info *server_info,
 310                                const char *form_name,
 311                                struct spoolss_AddFormInfo1 *form);
 312
 313 /**
 314  * @brief This function retrieves information about a specified form.
 315  *
 316  * @param[in]  mem_ctx  The talloc memory context to use.
 317  *
 318  * @param[in]  server_info The server supplied session info.
 319  *
 320  * @param[in]  form_name The name of the form to query.
 321  *
 322  * @param[out] form     A pointer to a form structure to fill out.
 323  *
 324  * @return              On success WERR_OK, a corresponding DOS error is
 325  *                      something went wrong.
 326  */
 327 WERROR winreg_printer_getform1(TALLOC_CTX *mem_ctx,
 328                                struct auth_serversupplied_info *server_info,
 329                                const char *form_name,
 330                                struct spoolss_FormInfo1 *form);
 331
 332 #endif /* _SRV_SPOOLSS_UITL_H */