RetroZilla/directory/xpcom/base/public/nsILDAPOperation.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 * 
 * ***** BEGIN LICENSE BLOCK *****
 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
 *
 * 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 SDK.
 *
 * The Initial Developer of the Original Code is
 * Netscape Communications Corporation.
 * Portions created by the Initial Developer are Copyright (C) 2000
 * the Initial Developer. All Rights Reserved.
 *
 * Contributor(s):
 *   Dan Mosedale <dmose@mozilla.org>
 *
 * Alternatively, the contents of this file may be used under the terms of
 * either the GNU General Public License Version 2 or later (the "GPL"), or
 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 * in which case the provisions of the GPL or the LGPL are applicable instead
 * of those above. If you wish to allow use of your version of this file only
 * under the terms of either the GPL or the LGPL, and not to allow others to
 * use your version of this file under the terms of the MPL, indicate your
 * decision by deleting the provisions above and replace them with the notice
 * and other provisions required by the GPL or the LGPL. If you do not delete
 * the provisions above, a recipient may use your version of this file under
 * the terms of any one of the MPL, the GPL or the LGPL.
 *
 * ***** END LICENSE BLOCK ***** */

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

interface nsILDAPMessage;
interface nsILDAPMessageListener;
interface nsIMutableArray;

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

typedef PRUint32 PRIntervalTime;

[scriptable, uuid(51f3b2f3-1f22-4fa8-9836-2e30e1471bff)]
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);

    /**
     * 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 aAttrCount        Number of attributes we request (0 for all)
     * @param aAttributes       Array of strings, holding the attrs we need
     * @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_INVALID_ARG
     * @exception NS_ERROR_LDAP_NOT_SUPPORTED
     * @exception NS_ERROR_LDAP_FILTER_ERROR
     * @exception NS_ERROR_UNEXPECTED
     */
    void searchExt(in AUTF8String aBaseDn, in PRInt32 aScope,
                   in AUTF8String aFilter, in unsigned long aAttrCount,
                   [array, size_is(aAttrCount)] in string aAttributes,
                   in PRIntervalTime aTimeOut, in PRInt32 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();
};