summaryrefslogtreecommitdiffstats
path: root/ldap/xpcom/public/nsILDAPMessage.idl
blob: 7b3298e48ca265aae00e48632a01be0684c01a49 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
/* -*- 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);
};