windows-64-bit-type-safety-20051105
[openafs.git] / 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