/* -*- 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"

interface nsILDAPBERValue;
interface nsILDAPOperation;

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

[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);
};