RetroZilla/directory/xpcom/base/public/nsILDAPMessage.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> (original author)
 *
 * 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"

interface nsILDAPBERValue;
interface nsILDAPOperation;

[scriptable, uuid(973ff50f-2002-4f0c-b57d-2242156139a2)]
interface nsILDAPMessage : nsISupports
{
    /**
     * The Distinguished Name of the entry associated with this message.
     * 
     * @exception NS_ERROR_OUT_OF_MEMORY        ran out of memory
     * @exception NS_ERROR_ILLEGAL_VALUE        null pointer passed in
     * @exception NS_ERROR_LDAP_DECODING_ERROR  problem during BER-decoding
     * @exception NS_ERROR_UNEXPECTED           bug or memory corruption
     */
    readonly attribute AUTF8String dn;

    /**
     * Get all the attributes in this message.
     *
     * @exception NS_ERROR_OUT_OF_MEMORY
     * @exception NS_ERROR_ILLEGAL_VALUE        null pointer passed in
     * @exception NS_ERROR_UNEXPECTED           bug or memory corruption
     * @exception NS_ERROR_LDAP_DECODING_ERROR  problem during BER decoding
     *
     * @return  array of all attributes in the current message
     */
    void getAttributes(out unsigned long count, 
                       [retval, array, size_is(count)] out string aAttributes);

    /**
     * Get an array of all the attribute values in this message.
     *
     * @param attr      The attribute whose values are to be returned
     * @param count     Number of values in the outbound array.
     * @param values    Array of values
     *
     * @exception NS_ERROR_UNEXPECTED           Bug or memory corruption
     * @exception NS_ERROR_LDAP_DECODING_ERROR  Attribute not found or other 
     *                                          decoding error.
     * @exception NS_ERROR_OUT_OF_MEMORY
     */
    void getValues(in string attr, out unsigned long count, 
                   [retval, array, size_is(count)] out wstring values);

    /**
     * The operation this message originated from
     * 
     * @exception NS_ERROR_NULL_POINTER         NULL pointer to getter
     */
    readonly attribute nsILDAPOperation operation;

    /**
     * The result code (aka lderrno) for this message.  
     *
     * IDL definitions for these constants live in nsILDAPErrors.idl.
     *
     * @exception NS_ERROR_ILLEGAL_VALUE    null pointer passed in
     */
    readonly attribute long errorCode;

    /**
     * The result type of this message.  Possible types listed below, the 
     * values chosen are taken from the draft-ietf-ldapext-ldap-c-api-04.txt
     * and are the same ones used in the ldap.h include file from the Mozilla
     * LDAP C SDK.
     *
     * @exception NS_ERROR_ILLEGAL_VALUE    null pointer passed in
     * @exception NS_ERROR_UNEXPECTED       internal error (possible memory
     *                                                      corruption)
     */
    readonly attribute long type;

    /**
     * Result of a bind operation
     */
    const long RES_BIND = 0x61;

    /**
     * An entry found in an search operation.
     */
    const long RES_SEARCH_ENTRY = 0x64;

    /**
     * An LDAPv3 search reference (a referral to another server)
     */
    const long RES_SEARCH_REFERENCE = 0x73;

    /** 
     * The result of a search operation (i.e. the search is done; no more
     * entries to follow).
     */
    const long RES_SEARCH_RESULT = 0x65;

    /**
     * The result of a modify operation.
     */
    const long RES_MODIFY = 0x67;

    /** 
     * The result of an add operation
     */
    const long RES_ADD = 0x69;
    
    /**
     * The result of a delete operation
     */
    const long RES_DELETE = 0x6B;

    /**
     * The result of an modify DN operation
     */
    const long RES_MODDN = 0x6D;

    /**
     * The result of a compare operation
     */
    const long RES_COMPARE = 0x6F;

    /** 
     * The result of an LDAPv3 extended operation
     */
    const long RES_EXTENDED = 0x78;

    /**
     * get an LDIF-like string representation of this message
     *
     * @return unicode encoded string representation.
     */
    wstring toUnicode();

    /**
     * Additional error information optionally sent by the server.
     */
    readonly attribute AUTF8String errorMessage;

    /**
     * In LDAPv3, when the server returns any of the following errors:
     * NO_SUCH_OBJECT, ALIAS_PROBLEM, INVALID_DN_SYNTAX, ALIAS_DEREF_PROBLEM,
     * it also returns the closest existing DN to the entry requested.
     */
    readonly attribute AUTF8String matchedDn;

    /**
     * Get an array of all the attribute values in this message (a wrapper
     * around the LDAP C SDK's get_values_len()).
     *
     * @param attr      The attribute whose values are to be returned
     * @param count     Number of values in the outbound array.
     * @param values    Array of nsILDAPBERValue objects
     *
     * @exception NS_ERROR_UNEXPECTED           Bug or memory corruption
     * @exception NS_ERROR_LDAP_DECODING_ERROR  Attribute not found or other 
     *                                          decoding error.
     * @exception NS_ERROR_OUT_OF_MEMORY
     */
    void getBinaryValues(in string attr, out unsigned long count,
                         [retval, array, size_is(count)] out nsILDAPBERValue values);
};