/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 * 
 * 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 Netscape are 
 * Copyright (C) 2000 Netscape Communications Corporation.  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 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 "nsILDAPOperation.idl"

/* hack around XPIDL bug 78848; when that's fixed, this can disappear */
%{C++
#include "nsAString.h"
%}

[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 wstring 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 AString 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 AString matchedDn;
};

.