1// $OpenLDAP$
2/*
3 * Copyright 2000-2011 The OpenLDAP Foundation, All Rights Reserved.
4 * COPYING RESTRICTIONS APPLY, see COPYRIGHT file
5 */
6
7
8#ifndef LDAP_ATTRIBUTE_H
9#define LDAP_ATTRIBUTE_H
10
11#include<iostream>
12#include<string>
13#include<ldap.h>
14#include<lber.h>
15
16#include <StringList.h>
17
18/**
19 * Represents the name an value(s) of an Attribute
20 */
21class LDAPAttribute{
22    public :
23        /**
24         * Default constructor.
25         * initializes an empty object.
26         */
27        LDAPAttribute();
28
29        /**
30         * Copy constructor.
31         * Copies all values of an Attribute to a new one
32         * @param attr   The Attribute that should be copied
33         */
34        LDAPAttribute(const LDAPAttribute& attr);
35
36        /**
37         * Construct an Attribute with a single string value
38         * @param name      The attribute's name (type)
39         * @param value     The string value of the attribute, if "" the
40         *                  attribute will have no values, for LDAPv3
41         *                  this values must be UTF-8 encoded
42         */
43        LDAPAttribute(const std::string& name, const std::string& value="");
44
45        /**
46         * Construct an attribute with multiple string values
47         * @param name      The attribute's name (type)
48         * @param values    A 0-terminated array of char*. Each char* specifies
49         *                  one value of the attribute (UTF-8 encoded)
50         */
51        LDAPAttribute(const char* name, char **values);
52
53        /**
54         * Construct an attribute with multiple string values
55         * @param name      The attribute's name (type)
56         * @param values    A list of strings. Each element specifies
57         *                  one value of the attribute (UTF-8 or binary
58         *                  encoded)
59         */
60        LDAPAttribute(const std::string& name, const StringList& values);
61
62        /**
63         * Construct an attribute with multiple binary coded values
64         * @param name      The attribute's name (type)
65         * @param values    0-terminated array of binary attribute values
66         *                  The BerValue struct is declared as:<BR>
67         *                  struct berval{
68         *                      unsigned long bv_len;
69         *                      char *bv_val;
70         *                  } BerValue;
71         */
72        LDAPAttribute(const char* name, BerValue **values);
73
74        /**
75         * Destructor
76         */
77        ~LDAPAttribute();
78
79        /**
80         * Add a single string value(bin/char) to the Attribute
81         * @param value Value that should be added, it is copied inside the
82         *              object
83         */
84        void addValue(const std::string& value);
85
86        /**
87         * Add a single binary value to the Attribute
88         * @param value The binary coded value that should be added to the
89         *              Attribute.
90         * @return  0  no problem <BR>
91         *          -1 failure (mem. allocation problem)
92         */
93        int addValue(const BerValue *value);
94
95        /**
96         * Set the values of the attribute. If the object contains some values
97         * already, they are deleted
98         * @param values    0-terminated array of char*, each char*
99         *                  representing a string value to add to the entry
100         *
101         * @return  0  no problem <BR>
102         *          -1 failure (mem. allocation problem)
103         */
104        int setValues(char** values);
105
106        /**
107         * Set the values of the attribute. If the object does already contain
108         * some values, they will be deleted
109         * @param values    0-terminated array of BerValue*, each BerValue
110         *                  representing a binary value to add to the entry
111         *
112         * @return  0  no problem <BR>
113         *          -1 failure (mem. allocation problem)
114         */
115        int setValues(BerValue** values);
116
117        /**
118         * Set the values of the attribute. If the object does already contain
119         * some values, they will be deleted
120         * @param values    A list of string-Objects. Each string is
121         *                  representing a string or binary value to add to
122         *                  the entry
123         */
124        void setValues(const StringList& values);
125
126        /**
127         * For interal use only.
128         * This method is used to translate the values of the Attribute to
129         * 0-terminated Array of BerValue-structs as used by the C-API
130         * @return  The Values of the Attribute as an 0-terminated Array of
131         *          BerValue* (is dynamically allocated, delete it after usage)
132         *          <BR>
133         *          0-pointer in case of error
134         */
135        BerValue** getBerValues() const;
136
137        /**
138         * @return The values of the array as a list of strings
139         */
140        const StringList& getValues() const;
141
142        /**
143         * @return The number of values of the attribute
144         */
145        int getNumValues() const;
146
147        /**
148         * @return The name(type) of the attribute
149         */
150        const std::string& getName() const ;
151
152        /**
153         * Sets the Attribute's name (type)
154         * @param the new name of the object
155         */
156        void setName(const std::string& name);
157
158        /**
159         * For internal use only.
160         *
161         * This method translate the attribute of the object into a
162         * LDAPMod-Structure as used by the C-API
163         */
164        LDAPMod* toLDAPMod() const ;
165
166        /**
167         * @return true If the attribute contains non-printable attributes
168         */
169        bool isNotPrintable() const ;
170
171    private :
172        std::string m_name;
173        StringList m_values;
174
175    /**
176     * This method can be used to dump the data of a LDAPResult-Object.
177     * It is only useful for debugging purposes at the moment
178     */
179    friend std::ostream& operator << (std::ostream& s, const LDAPAttribute& attr);
180};
181#endif //#ifndef LDAP_ATTRIBUTE_H
182