/* 
 * The contents of this file are subject to the Mozilla Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/MPL/
 * 
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 * 
 * The Original Code is the mozilla.org LDAP XPCOM component.
 * 
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are 
 * Copyright (C) 2000 Netscape Communications Corporation.  All
 * Rights Reserved.
 * 
 * Contributor(s): Dan Mosedale <dmose@mozilla.org>
 * 
 * Alternatively, the contents of this file may be used under the
 * terms of the GNU General Public License Version 2 or later (the
 * "GPL"), in which case the provisions of the GPL are applicable 
 * instead of those above.  If you wish to allow use of your 
 * version of this file only under the terms of the GPL and not to
 * allow others to use your version of this file under the MPL,
 * indicate your decision by deleting the provisions above and
 * replace them with the notice and other provisions required by
 * the GPL.  If you do not delete the provisions above, a recipient
 * may use your version of this file under either the MPL or the
 * GPL.
 */

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

interface nsILDAPMessage;
interface nsILDAPMessageListener;

typedef PRUint32 PRIntervalTime;

[scriptable, uuid(fd3d413b-14b0-49c4-8348-a4fc0edba9ff)]
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;

    /**
     * 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.
     *
     * @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);

    /**
     * wrapper for ldap_simple_bind()
     * 
     * @param passwd    the password used for binding; NULL for anon-binds
     *
     * @exception NS_ERROR_LDAP_ENCODING_ERROR	problem encoding bind request
     * @exception NS_ERROR_FAILURE 		server down (XXX rebinds?)
     * @exception NS_ERROR_OUT_OF_MEMORY	ran out of memory
     * @exception NS_ERROR_UNEXPECTED		internal error
     * 
     */
    void simpleBind(in string passwd);

    // wrapper for ldap_search_url()
    // XXX this doesn't currently work right, because the connection has 
    // doesn't know what result came for whom.  also, the it calls
    // a synchronous bind function under the hood
    //
    // XXXdmose should probably get rid of this method, due to it's 
    // synchronity, and since we have other classes to 
    //
    void urlSearch(in string url, in boolean attrsonly);

    /**
     * wrapper for ldap_search_ext(): kicks off an async search request.
     *
     * @param aBaseDn           Base DN to search
     * @param aScope            One of LDAP_SCOPE_{BASE,ONELEVEL,SUBTREE}
     * @param aFilter           Search filter
     * @param aTimeOut          How long to wait
     * @param aSizeLimit        Maximum number of entries to return.
     *
     * @exception NS_ERROR_NOT_INITIALIZED
     * @exception NS_ERROR_LDAP_ENCODING_ERROR
     * @exception NS_ERROR_LDAP_SERVER_DOWN
     * @exception NS_ERROR_OUT_OF_MEMORY
     * @exception NS_ERROR_LDAP_NOT_SUPPORTED
     *
     * XXX doesn't currently handle LDAPControl params
     */
    void searchExt(in string aBaseDn, in PRInt32 aScope,
                   in string aFilter, in PRIntervalTime aTimeOut,
                   in PRInt32 aSizeLimit);

    /**  
     * wrapper for ldap_abandon_ext() with NULL LDAPControl
     * parameters, equivalent to old-style ldap_abandon(), thus the name.
     *
     * @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_UNEXPECTED		internal error
     */
    void abandon();
};
