summaryrefslogtreecommitdiffstats
path: root/ldap/xpcom/public/nsILDAPOperation.idl
blob: f3b9e6e7a218c51c6798207967b200891670ac1d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 * 
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"
#include "nsILDAPConnection.idl"
#include "nsIAuthModule.idl"

interface nsILDAPMessage;
interface nsILDAPMessageListener;
interface nsILDAPModification;
interface nsIMutableArray;
interface nsIArray;

%{C++
#define NS_LDAPOPERATION_CONTRACTID "@mozilla.org/network/ldap-operation;1" 
%}

// XXXdmose check to make sure ctl-related err codes documented

typedef uint32_t PRIntervalTime;

[scriptable, uuid(4dfb1b19-fc8f-4525-92e7-f97b78a9747a)]
interface nsILDAPOperation : nsISupports
{
    /**
     * The connection this operation is on. 
     * 
     * @exception NS_ERROR_ILLEGAL_VALUE        a NULL pointer was passed in
     */
    readonly attribute nsILDAPConnection connection;

    /**
     * Callback for individual result messages related to this operation (set
     * by the init() method).  This is actually an nsISupports proxy object, 
     * as the callback will happen from another thread.
     * 
     * @exception NS_ERROR_ILLEGAL_VALUE        a NULL pointer was passed in
     */
    readonly attribute nsILDAPMessageListener messageListener;

    /**
     * The message-id associated with this operation.
     *
     * @exception NS_ERROR_ILLEGAL_VALUE        a NULL pointer was passed in
     */
    readonly attribute long messageID;

    /**
     * private parameter (anything caller desires)
     */
    attribute nsISupports closure;

    /**
     * No time and/or size limit specified
     */
    const long NO_LIMIT = 0;

    /**
     * If specified, these arrays of nsILDAPControls are passed into the LDAP
     * C SDK for any extended operations (ie method calls on this interface
     * ending in "Ext").
     */
    attribute nsIMutableArray serverControls;
    attribute nsIMutableArray clientControls;

    /**
     * Initializes this operation.  Must be called prior to initiating
     * any actual operations.  Note that by default, the aMessageListener
     * callbacks happen on the LDAP connection thread.  If you need them
     * to happen on the main thread (or any other thread), then you should
     * created an nsISupports proxy object and pass that in.
     *
     * @param aConnection       connection this operation should use
     * @param aMessageListener  interface used to call back the results.
     * @param aClosure          private parameter (anything caller desires)
     *
     * @exception NS_ERROR_ILLEGAL_VALUE        a NULL pointer was passed in
     * @exception NS_ERROR_UNEXPECTED           failed to get connection handle
     */
    void init(in nsILDAPConnection aConnection, 
              in nsILDAPMessageListener aMessageListener,
              in nsISupports aClosure);

    /**
     * Asynchronously authenticate to the LDAP server.
     * 
     * @param passwd    the password used for binding; NULL for anon-binds
     *
     * @exception NS_ERROR_LDAP_ENCODING_ERROR  problem encoding bind request
     * @exception NS_ERROR_LDAP_SERVER_DOWN     server down (XXX rebinds?)
     * @exception NS_ERROR_LDAP_CONNECT_ERROR   connection failed or lost
     * @exception NS_ERROR_OUT_OF_MEMORY        ran out of memory
     * @exception NS_ERROR_UNEXPECTED           internal error
     */
    void simpleBind(in AUTF8String passwd);

    /**
     * Asynchronously perform a SASL bind against the LDAP server
     *
     * @param service    the host name of the service being connected to
     * @param mechanism  the name of the SASL mechanism in use
     * @param authModule the nsIAuthModule to be used to perform the operation
     *
     */
    void saslBind(in ACString service, in ACString mechanism, 
                  in nsIAuthModule authModule);

    /**
     * Continue a SASL bind operation
     *
     * @param token     the next SASL token to send to the server
     * @param tokenLen  the length of the token to send
     *
     */
    void saslStep(in string token, in unsigned long tokenLen);

    /**
     * Kicks off an asynchronous add request.  The "ext" stands for 
     * "extensions", and is intended to convey that this method will
     * eventually support the extensions described in the
     * draft-ietf-ldapext-ldap-c-api-04.txt Internet Draft.
     *
     * @param aBaseDn           Base DN to add
     * @param aModCount         Number of modifications
     * @param aMods             Array of modifications
     *
     * @exception NS_ERROR_NOT_INITIALIZED      operation not initialized
     * @exception NS_ERROR_INVALID_ARG          invalid argument
     * @exception NS_ERROR_LDAP_ENCODING_ERROR  error during BER-encoding
     * @exception NS_ERROR_LDAP_SERVER_DOWN     the LDAP server did not
     *                                          receive the request or the
     *                                          connection was lost
     * @exception NS_ERROR_OUT_OF_MEMORY        ran out of memory
     * @exception NS_ERROR_LDAP_NOT_SUPPORTED   not supported in the version
     *                                          of the LDAP protocol that the
     *                                          client is using
     * @exception NS_ERROR_UNEXPECTED           an unexpected error has
     *                                          occurred
     *
     * XXX doesn't currently handle LDAPControl params
     */
    void addExt(in AUTF8String aBaseDn, in nsIArray aMods);

    /**
     * Kicks off an asynchronous delete request.  The "ext" stands for 
     * "extensions", and is intended to convey that this method will
     * eventually support the extensions described in the
     * draft-ietf-ldapext-ldap-c-api-04.txt Internet Draft.
     *
     * @param aBaseDn           Base DN to delete
     *
     * @exception NS_ERROR_NOT_INITIALIZED      operation not initialized
     * @exception NS_ERROR_INVALID_ARG          invalid argument
     * @exception NS_ERROR_LDAP_ENCODING_ERROR  error during BER-encoding
     * @exception NS_ERROR_LDAP_SERVER_DOWN     the LDAP server did not
     *                                          receive the request or the
     *                                          connection was lost
     * @exception NS_ERROR_OUT_OF_MEMORY        ran out of memory
     * @exception NS_ERROR_LDAP_NOT_SUPPORTED   not supported in the version
     *                                          of the LDAP protocol that the
     *                                          client is using
     * @exception NS_ERROR_UNEXPECTED           an unexpected error has
     *                                          occurred
     *
     * XXX doesn't currently handle LDAPControl params
     */
    void deleteExt(in AUTF8String aBaseDn);

    /**
     * Kicks off an asynchronous modify request.  The "ext" stands for 
     * "extensions", and is intended to convey that this method will
     * eventually support the extensions described in the
     * draft-ietf-ldapext-ldap-c-api-04.txt Internet Draft.
     *
     * @param aBaseDn           Base DN to modify
     * @param aModCount         Number of modifications
     * @param aMods             Array of modifications
     *
     * @exception NS_ERROR_NOT_INITIALIZED      operation not initialized
     * @exception NS_ERROR_INVALID_ARG          invalid argument
     * @exception NS_ERROR_LDAP_ENCODING_ERROR  error during BER-encoding
     * @exception NS_ERROR_LDAP_SERVER_DOWN     the LDAP server did not
     *                                          receive the request or the
     *                                          connection was lost
     * @exception NS_ERROR_OUT_OF_MEMORY        ran out of memory
     * @exception NS_ERROR_LDAP_NOT_SUPPORTED   not supported in the version
     *                                          of the LDAP protocol that the
     *                                          client is using
     * @exception NS_ERROR_UNEXPECTED           an unexpected error has
     *                                          occurred
     *
     * XXX doesn't currently handle LDAPControl params
     */
    void modifyExt(in AUTF8String aBaseDn, in nsIArray aMods);

    /**
     * Kicks off an asynchronous rename request.
     *
     * @param aBaseDn           Base DN to rename
     * @param aNewRDn           New relative DN
     * @param aNewParent        DN of the new parent under which to move the
     *                          entry
     * @param aDeleteOldRDn     Indicates whether to remove the old relative
     *                          DN as a value in the entry or not
     *
     * @exception NS_ERROR_NOT_INITIALIZED      operation not initialized
     * @exception NS_ERROR_INVALID_ARG          invalid argument
     * @exception NS_ERROR_LDAP_ENCODING_ERROR  error during BER-encoding
     * @exception NS_ERROR_LDAP_SERVER_DOWN     the LDAP server did not
     *                                          receive the request or the
     *                                          connection was lost
     * @exception NS_ERROR_OUT_OF_MEMORY        ran out of memory
     * @exception NS_ERROR_LDAP_NOT_SUPPORTED   not supported in the version
     *                                          of the LDAP protocol that the
     *                                          client is using
     * @exception NS_ERROR_UNEXPECTED           an unexpected error has
     *                                          occurred
     *
     * XXX doesn't currently handle LDAPControl params
     */
    void rename(in AUTF8String aBaseDn, in AUTF8String aNewRDn,
                in AUTF8String aNewParent, in boolean aDeleteOldRDn);

    /**
     * Kicks off an asynchronous search request.  The "ext" stands for 
     * "extensions", and is intended to convey that this method will
     * eventually support the extensions described in the
     * draft-ietf-ldapext-ldap-c-api-04.txt Internet Draft.
     *
     * @param aBaseDn           Base DN to search
     * @param aScope            One of SCOPE_{BASE,ONELEVEL,SUBTREE}
     * @param aFilter           Search filter
     * @param aAttributes       Comma separated list of values, holding the
     *                          attributes we need
     * @param aTimeOut          How long to wait
     * @param aSizeLimit        Maximum number of entries to return.
     *
     * @exception NS_ERROR_NOT_INITIALIZED      operation not initialized
     * @exception NS_ERROR_LDAP_ENCODING_ERROR  error during BER-encoding
     * @exception NS_ERROR_LDAP_SERVER_DOWN     the LDAP server did not
     *                                          receive the request or the
     *                                          connection was lost
     * @exception NS_ERROR_OUT_OF_MEMORY        ran out of memory
     * @exception NS_ERROR_INVALID_ARG          invalid argument
     * @exception NS_ERROR_LDAP_NOT_SUPPORTED   not supported in the version
     *                                          of the LDAP protocol that the
     *                                          client is using
     * @exception NS_ERROR_LDAP_FILTER_ERROR
     * @exception NS_ERROR_UNEXPECTED
     */
    void searchExt(in AUTF8String aBaseDn, in int32_t aScope,
                   in AUTF8String aFilter, in ACString aAttributes,
                   in PRIntervalTime aTimeOut, in int32_t aSizeLimit);

    /**  
     * Cancels an async operation that is in progress.
     *
     * XXX controls not supported yet
     *
     * @exception NS_ERROR_NOT_IMPLEMENTED      server or client controls
     *                                          were set on this object
     * @exception NS_ERROR_NOT_INITIALIZED      operation not initialized
     * @exception NS_ERROR_LDAP_ENCODING_ERROR  error during BER-encoding
     * @exception NS_ERROR_LDAP_SERVER_DOWN     the LDAP server did not
     *                                          receive the request or the
     *                                          connection was lost
     * @exception NS_ERROR_OUT_OF_MEMORY        out of memory
     * @exception NS_ERROR_INVALID_ARG          invalid argument
     * @exception NS_ERROR_UNEXPECTED           internal error
     */
    void abandonExt();
};