src/WINNT/afsadmsvr/ITaAfsAdmSvr.idl

   1 /*
   2  * Copyright 2000, International Business Machines Corporation and others.
   3  * All Rights Reserved.
   4  *
   5  * This software has been released under the terms of the IBM Public
   6  * License.  For details, see the LICENSE file in the top-level source
   7  * directory or online at http://www.openafs.org/dl/license10.html
   8  */
   9
  10 [
  11 uuid(ae274620-dea3-11d1-bfb3-00a024c0d1ef),
  12 version(1.0),
  13 pointer_default(unique),
  14 implicit_handle(handle_t hBindTaAfsAdminSvr)
  15 ]
  16 interface ITaAfsAdminSvr
  17 {
  18    import "ITaAfsAdmSvrTypes.idl";
  19
  20    // AfsAdmSvr_Connect
  21    // ...obtains a cookie to represent the calling process. The cookie should
  22    //    be freed with AfsAdmSvr_Disconnect when the process disconnects.
  23    //
  24    int AfsAdmSvr_Connect (
  25       [in]      STRING szClientAddress,
  26       [out]     UINT_PTR *pidClient,
  27       [out]     ULONG *pStatus
  28    );
  29
  30    // AfsAdmSvr_Disconnect
  31    // ...releases and invalidates the cookie representing the calling process.
  32    //
  33    int AfsAdmSvr_Disconnect (
  34       [in]      UINT_PTR idClient,
  35       [out]     ULONG *pStatus
  36    );
  37
  38
  39    // AfsAdmSvr_Ping
  40    // ...reminds the admin server that the specified client is still around.
  41    //    this call should be made at least every csecAFSADMSVR_CLIENT_PING
  42    //    seconds, lest the admin server think you've disconnected. (The client
  43    //    library TaAfsAdmSvrClient.lib automatically handles this.)
  44    //
  45    int AfsAdmSvr_Ping (
  46       [in]      UINT_PTR idClient,
  47       [out]     ULONG *pStatus
  48    );
  49    const DWORD csecAFSADMSVR_CLIENT_PING = (2L * 60L);  // 2 minutes
  50
  51
  52    // AfsAdmSvr_CrackCredentials
  53    // ...obtains information about the supplied credentials token.
  54    //
  55    int AfsAdmSvr_CrackCredentials (
  56       [in]      UINT_PTR idClient,
  57       [in]      UINT_PTR hCreds,
  58       [out]     STRING pszCell,
  59       [out]     STRING pszUser,
  60       [out]     SYSTEMTIME *pstExpiration,
  61       [out]     ULONG *pStatus
  62    );
  63
  64    // AfsAdmSvr_GetCredentials
  65    // ...queries the user's current AFS credentials for the specified cell.
  66    //    if the user already has credentials in the cell, returns a nonzero
  67    //    token {hCreds}, suitable for use in AfsAdmSvr_OpenCell().
  68    //
  69    UINT_PTR AfsAdmSvr_GetCredentials (
  70       [in]      UINT_PTR idClient,
  71       [in]      STRING pszCell,
  72       [out]     ULONG *pStatus
  73    );
  74
  75    // AfsAdmSvr_SetCredentials
  76    // ...obtains new AFS credentials within the administrative server process
  77    //    on behalf of the specified user. if successful, returns a nonzero
  78    //    token {hCreds}, suitable for use in AfsAdmSvr_OpenCell().
  79    //
  80    UINT_PTR AfsAdmSvr_SetCredentials (
  81       [in]      UINT_PTR idClient,
  82       [in]      STRING pszCell,
  83       [in]      STRING pszUser,
  84       [in]      STRING pszPassword,
  85       [out]     ULONG *pStatus
  86    );
  87
  88    // AfsAdmSvr_PushCredentials
  89    // ...requests that the specified AFS credentials be used hereafter
  90    //    when manipulating the specified cell. You should follow this
  91    //    call with a Refresh request if necessary.
  92    //
  93    int AfsAdmSvr_PushCredentials (
  94       [in]      UINT_PTR idClient,
  95       [in]      UINT_PTR hCreds,
  96       [in]      ASID idCell,
  97       [out]     ULONG *pStatus
  98    );
  99
 100
 101    // AfsAdmSvr_GetLocalCell
 102    // ...obtains the name of the primary cell used by the admin server
 103    //
 104    int AfsAdmSvr_GetLocalCell (
 105       [in]      UINT_PTR idClient,
 106       [out]     STRING pszCellName,
 107       [out]     ULONG *pStatus
 108    );
 109
 110
 111    // AfsAdmSvr_ErrorCodeTranslate
 112    // ...translates an error code into a readable string
 113    //
 114    int AfsAdmSvr_ErrorCodeTranslate (
 115       [in]      UINT_PTR idClient,
 116       [in]      ULONG code,
 117       [in]      LANGID idLanguage,    // pass 0 for default language at server
 118       [out]     STRING pszErrorText,
 119       [out]     ULONG *pStatus
 120    );
 121
 122
 123    // AfsAdmSvr_GetAction
 124    // ...returns information about a particular operation in progress.
 125    //
 126    int AfsAdmSvr_GetAction (
 127       [in]      UINT_PTR idClient,
 128       [in]      DWORD idAction,
 129       [out]     LPASACTION pAction,
 130       [out]     ULONG *pStatus
 131    );
 132
 133
 134    // AfsAdmSvr_GetActions
 135    // ...returns a list of operations in progress. The list returned can
 136    //    be constrained to only including those operations initiated by
 137    //    a particular client and/or performed in a particular cell.
 138    //
 139    int AfsAdmSvr_GetActions (
 140       [in]      UINT_PTR idClient,
 141       [in]      UINT_PTR idClientSearch,   // 0 to return for all clients
 142       [in]      ASID idCellSearch,      // 0 to return for all cells
 143       [out]     LPASACTIONLIST *ppList,
 144       [out]     ULONG *pStatus
 145    );
 146
 147
 148    // AfsAdmSvr_OpenCell
 149    // ...opens a cell for administration.
 150    //
 151    int AfsAdmSvr_OpenCell (
 152       [in]      UINT_PTR idClient,
 153       [in]      UINT_PTR hCreds,
 154       [in]      STRING pszCellName,
 155       [in]      DWORD dwScopeFlags,
 156       [out]     ASID *pidCell,
 157       [out]     ULONG *pStatus
 158    );
 159    const DWORD AFSADMSVR_SCOPE_VOLUMES = 0x00000001;
 160    const DWORD AFSADMSVR_SCOPE_USERS   = 0x00000002;
 161
 162    // AfsAdmSvr_CloseCell
 163    // ...used by client to open a cell for administration.
 164    //
 165    int AfsAdmSvr_CloseCell (
 166       [in]      UINT_PTR idClient,
 167       [in]      ASID idCell,
 168       [out]     ULONG *pStatus
 169    );
 170
 171
 172    // AfsAdmSvr_FindObject
 173    // AfsAdmSvr_FindObjects
 174    // ...used to search through all objects in the cell, obtaining a list
 175    //    of those which match the specified criteria. For FindObjects, the
 176    //    {*ppList} parameter will be filled in with an allocated list of ASID
 177    //    objects, and should be freed using the AfsAdmSvr_FreeAsidList()
 178    //    routine (clients using the TaAfsAdmSvrClient.lib library should call
 179    //    asc_AsidListFree(), which is a wrapper for the former routine).
 180    //    The _FindObject routine can be used to find exactly one object--for
 181    //    instance, finding the ASID for a particular user or volume--while
 182    //    the _FindObjects routine returns a list of all objects which
 183    //    match the specified criteria--all volumes on a partition, or all
 184    //    users named "b*" within a cell.
 185    //
 186    int AfsAdmSvr_FindObject (
 187       [in]      UINT_PTR idClient,
 188       [in]      ASID idSearchScope,
 189       [in]      ASOBJTYPE ObjectType,
 190       [in]      AFSADMSVR_SEARCH_REFRESH SearchRefresh,
 191       [in]      STRING szName,
 192       [out]     ASID *pidObject,
 193       [out]     ULONG *pStatus
 194    );
 195
 196    int AfsAdmSvr_FindObjects (
 197       [in]      UINT_PTR idClient,
 198       [in]      ASID idSearchScope,
 199       [in]      ASOBJTYPE ObjectType,
 200       [in]      AFSADMSVR_SEARCH_REFRESH SearchRefresh,
 201       [in]      STRING szPattern,
 202       [in]      LPAFSADMSVR_SEARCH_PARAMS pSearchParams,
 203       [out]     LPASIDLIST *ppList,
 204       [out]     ULONG *pStatus
 205    );
 206
 207
 208    // AfsAdmSvr_GetObject
 209    // AfsAdmSvr_GetObjects
 210    // ...returns server-cached information about the specified object (or
 211    //    objects).
 212    //
 213    int AfsAdmSvr_GetObject (
 214       [in]      UINT_PTR idClient,
 215       [in]      AFSADMSVR_GET_TYPE GetType,
 216       [in]      AFSADMSVR_GET_LEVEL GetLevel,
 217       [in]      ASID idObject,
 218       [in]      UINT_PTR verProperties,  // can be 0 if not RETURN_IF_OUT_OF_DATE
 219       [out]     LPASOBJPROP pProperties,
 220       [out]     ULONG *pStatus
 221    );
 222
 223    int AfsAdmSvr_GetObjects (
 224       [in]      UINT_PTR idClient,
 225       [in]      AFSADMSVR_GET_TYPE GetType,
 226       [in]      AFSADMSVR_GET_LEVEL GetLevel,
 227       [in]      LPASIDLIST pListObjects,  // lParam used as verProperties
 228       [out]     LPASOBJPROPLIST *ppListObjectProperties,
 229       [out]     ULONG *pStatus
 230    );
 231
 232
 233    // AfsAdmSvr_RefreshObject
 234    // AfsAdmSvr_RefreshObjects
 235    // ...invalidates the server's cache of information about the specified
 236    //    object or objects.
 237    //
 238    int AfsAdmSvr_RefreshObject (
 239       [in]      UINT_PTR idClient,
 240       [in]      ASID idObject,
 241       [out]     ULONG *pStatus
 242    );
 243
 244    int AfsAdmSvr_RefreshObjects (
 245       [in]      UINT_PTR idClient,
 246       [in]      LPASIDLIST pListObjects,
 247       [out]     ULONG *pStatus
 248    );
 249
 250
 251    // AfsAdmSvr_CallbackHost
 252    // ...provides a context in which the server can issue callback functions
 253    //    via the AfsAdmSvrCallBack_* routines, which the client must implement.
 254    //    This routine will only return if the server is shut down. It should
 255    //    be called on a dedicated thread by the client. (TaAfsAdmSvrClient.lib
 256    //    automatically handles this.)
 257    //
 258    void AfsAdmSvr_CallbackHost (void);
 259
 260    // AfsAdmSvrCallback_Action
 261    // ...called by the server in the context of the CallbackHost() routine;
 262    //    this routine is used to notify the client whenever an action is
 263    //    initiated or completed.
 264    //
 265    [callback] void AfsAdmSvrCallback_Action (
 266       [in]      LPASACTION pAction,
 267       [in]      BOOL fFinished
 268    );
 269
 270    // AfsAdmSvr_GetRandomKey
 271    // ...returns a randomly-generated 8-byte encryption key
 272    //
 273    int AfsAdmSvr_GetRandomKey (
 274       [in]      UINT_PTR idClient,
 275       [in]      ASID idCell,
 276       [out]     BYTE keyData[ ENCRYPTIONKEYLENGTH ],
 277       [out]     ULONG *pStatus
 278    );
 279
 280    // AfsAdmSvr_ChangeUser
 281    // ...changes a user account's properties.
 282    //
 283    int AfsAdmSvr_ChangeUser (
 284       [in]      UINT_PTR idClient,
 285       [in]      ASID idCell,
 286       [in]      ASID idUser,
 287       [in]      LPAFSADMSVR_CHANGEUSER_PARAMS pChange,
 288       [out]     ULONG *pStatus
 289    );
 290
 291    // AfsAdmSvr_GetGroupMembership
 292    // ...retrieves the list of groups to which a user or group belongs
 293    //
 294    int AfsAdmSvr_GetGroupMembership (
 295       [in]      UINT_PTR idClient,
 296       [in]      ASID idCell,
 297       [in]      ASID idMember,
 298       [out]     LPASIDLIST *ppAsidList,
 299       [out]     ULONG *pStatus
 300    );
 301
 302    // AfsAdmSvr_GetGroupOwnership
 303    // ...retrieves the list of groups which a user or group owns
 304    //
 305    int AfsAdmSvr_GetGroupOwnership (
 306       [in]      UINT_PTR idClient,
 307       [in]      ASID idCell,
 308       [in]      ASID idOwner,
 309       [out]     LPASIDLIST *ppAsidList,
 310       [out]     ULONG *pStatus
 311    );
 312
 313    // AfsAdmSvr_ChangeGroup
 314    // ...changes a PTS group's properties.
 315    //
 316    int AfsAdmSvr_ChangeGroup (
 317       [in]      UINT_PTR idClient,
 318       [in]      ASID idCell,
 319       [in]      ASID idGroup,
 320       [in]      LPAFSADMSVR_CHANGEGROUP_PARAMS pChange,
 321       [out]     ULONG *pStatus
 322    );
 323
 324    // AfsAdmSvr_GetGroupMembers
 325    // ...retrieves the list of users which belong to a group
 326    //
 327    int AfsAdmSvr_GetGroupMembers (
 328       [in]      UINT_PTR idClient,
 329       [in]      ASID idCell,
 330       [in]      ASID idGroup,
 331       [out]     LPASIDLIST *ppAsidList,
 332       [out]     ULONG *pStatus
 333    );
 334
 335    // AfsAdmSvr_AddGroupMember
 336    // ...adds a member to the specified group
 337    //
 338    int AfsAdmSvr_AddGroupMember (
 339       [in]      UINT_PTR idClient,
 340       [in]      ASID idCell,
 341       [in]      ASID idGroup,
 342       [in]      ASID idMember,
 343       [out]     ULONG *pStatus
 344    );
 345
 346    // AfsAdmSvr_RemoveGroupMember
 347    // ...removes a member from the specified group
 348    //
 349    int AfsAdmSvr_RemoveGroupMember (
 350       [in]      UINT_PTR idClient,
 351       [in]      ASID idCell,
 352       [in]      ASID idGroup,
 353       [in]      ASID idMember,
 354       [out]     ULONG *pStatus
 355    );
 356
 357    // AfsAdmSvr_RenameGroup
 358    // ...changes a group's name
 359    //
 360    int AfsAdmSvr_RenameGroup (
 361       [in]      UINT_PTR idClient,
 362       [in]      ASID idCell,
 363       [in]      ASID idGroup,
 364       [in]      STRING szNewGroupName,
 365       [out]     ULONG *pStatus
 366    );
 367
 368    // AfsAdmSvr_CreateGroup
 369    // ...creates a new PTS group
 370    //
 371    int AfsAdmSvr_CreateGroup (
 372       [in]      UINT_PTR idClient,
 373       [in]      ASID idCell,
 374       [in]      LPAFSADMSVR_CREATEGROUP_PARAMS pCreate,
 375       [out]     ASID *pidGroup,
 376       [out]     ULONG *pStatus
 377    );
 378
 379    // AfsAdmSvr_DeleteGroup
 380    // ...deletes a PTS group
 381    //
 382    int AfsAdmSvr_DeleteGroup (
 383       [in]      UINT_PTR idClient,
 384       [in]      ASID idCell,
 385       [in]      ASID idGroup,
 386       [out]     ULONG *pStatus
 387    );
 388
 389    // AfsAdmSvr_SetUserPassword
 390    // ...changes the password for the specified user account. Pass a non-empty
 391    //    string in {keyString} to encrypt the specified string; otherwise,
 392    //    pass a valid encryption key in {keyData}.
 393    //
 394    int AfsAdmSvr_SetUserPassword (
 395       [in]      UINT_PTR idClient,
 396       [in]      ASID idCell,
 397       [in]      ASID idUser,
 398       [in]      int keyVersion,
 399       [in]      STRING keyString,
 400       [in]      BYTE keyData[ ENCRYPTIONKEYLENGTH ],
 401       [out]     ULONG *pStatus
 402    );
 403
 404    // AfsAdmSvr_UnlockUser
 405    // ...unlocks a user's account
 406    //
 407    int AfsAdmSvr_UnlockUser (
 408       [in]      UINT_PTR idClient,
 409       [in]      ASID idCell,
 410       [in]      ASID idUser,
 411       [out]     ULONG *pStatus
 412    );
 413
 414    // AfsAdmSvr_CreateUser
 415    // ...creates a new user account
 416    //
 417    int AfsAdmSvr_CreateUser (
 418       [in]      UINT_PTR idClient,
 419       [in]      ASID idCell,
 420       [in]      LPAFSADMSVR_CREATEUSER_PARAMS pCreate,
 421       [out]     ASID *pidUser,
 422       [out]     ULONG *pStatus
 423    );
 424
 425    // AfsAdmSvr_DeleteUser
 426    // ...deletes a user account
 427    //
 428    int AfsAdmSvr_DeleteUser (
 429       [in]      UINT_PTR idClient,
 430       [in]      ASID idCell,
 431       [in]      ASID idUser,
 432       [in]      LPAFSADMSVR_DELETEUSER_PARAMS pDelete,
 433       [out]     ULONG *pStatus
 434    );
 435
 436    // AfsAdmSvr_ChangeCell
 437    // ...changes a cell's properties.
 438    //
 439    int AfsAdmSvr_ChangeCell (
 440       [in]      UINT_PTR idClient,
 441       [in]      ASID idCell,
 442       [in]      LPAFSADMSVR_CHANGECELL_PARAMS pChange,
 443       [out]     ULONG *pStatus
 444    );
 445
 446    // AfsAdmSvr_SetRefreshRate
 447    // ...changes the refresh rate for a specific cell
 448    //
 449    int AfsAdmSvr_SetRefreshRate (
 450       [in]      UINT_PTR idClient,
 451       [in]      ASID idCell,
 452       [in]      ULONG cminRefreshRate,
 453       [out]     ULONG *pStatus
 454    );
 455
 456 }
 457