1 kumpf 1.1 //%2005////////////////////////////////////////////////////////////////////////
  2           //
  3           // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
  4           // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
  5           // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
  6           // IBM Corp.; EMC Corporation, The Open Group.
  7           // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
  8           // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
  9           // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
 10           // EMC Corporation; VERITAS Software Corporation; The Open Group.
 11           //
 12           // Permission is hereby granted, free of charge, to any person obtaining a copy
 13           // of this software and associated documentation files (the "Software"), to
 14           // deal in the Software without restriction, including without limitation the
 15           // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 16           // sell copies of the Software, and to permit persons to whom the Software is
 17           // furnished to do so, subject to the following conditions:
 18           // 
 19           // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
 20           // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
 21           // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
 22 kumpf 1.1 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 23           // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 24           // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
 25           // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 26           // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 27           //
 28           //==============================================================================
 29           //
 30           //%/////////////////////////////////////////////////////////////////////////////
 31           
 32           #ifndef Pegasus_AcceptLanguageList_h
 33           #define Pegasus_AcceptLanguageList_h
 34           
 35           #include <Pegasus/Common/Config.h>
 36           #include <Pegasus/Common/LanguageTag.h>
 37           
 38           #ifdef PEGASUS_USE_EXPERIMENTAL_INTERFACES
 39           
 40           PEGASUS_NAMESPACE_BEGIN
 41           
 42           class AcceptLanguageListRep;
 43 kumpf 1.1 
 44           //////////////////////////////////////////////////////////////
 45           //
 46           // AcceptLanguageList
 47           //
 48           //////////////////////////////////////////////////////////////
 49           
 50           /** <I><B>Experimental Interface</B></I><BR>
 51               This class represents an list of languages that a reader can understand
 52               (as may be specified in an HTTP Accept-Language header value).  It is
 53               managed as a prioritized list of LanguageTag objects and quality values.
 54            */
 55           class PEGASUS_COMMON_LINKAGE AcceptLanguageList
 56           {
 57           public:
 58           
 59               /**
 60                   Constructs an empty AcceptLanguageList object.
 61                */
 62               AcceptLanguageList();
 63           
 64 kumpf 1.1     /**
 65                   Copy constructor.
 66                   @param acceptLanguages The AcceptLanguageList object to copy.
 67                */
 68               AcceptLanguageList(const AcceptLanguageList& acceptLanguages);
 69           
 70               /**
 71                   Destructor.
 72                */
 73               ~AcceptLanguageList();
 74           
 75               /**
 76                   Assignment operator.
 77                   @param acceptLanguages The AcceptLanguageList object to copy.
 78                */
 79               AcceptLanguageList& operator=(const AcceptLanguageList& acceptLanguages);
 80           
 81               /**
 82                   Returns the number of LanguagesTags in the AcceptLanguageList object.
 83                   @return Integer size of the AcceptLanguageList list.
 84                */
 85 kumpf 1.1     Uint32 size() const;
 86           
 87               /**
 88                   Accesses an LanguageTag at a specified index.
 89                   @param index Integer index of the LanguageTag to access.
 90                   Valid indices range from 0 to size()-1.
 91                   @return The LanguageTag corresponding to the specified index.
 92                   @exception IndexOutOfBoundsException If the specified index is out of
 93                   range.
 94                */
 95               LanguageTag getLanguageTag(Uint32 index) const;
 96           
 97               /**
 98                   Accesses a quality value at a specified index (corresponding to a
 99                   language tag).
100                   @param index Integer index of the quality value to access.
101                   Valid indices range from 0 to size()-1.
102                   @return The quality value corresponding to the specified index.
103                   @exception IndexOutOfBoundsException If the specified index is out of
104                   range.
105                */
106 kumpf 1.1     Real32 getQualityValue(Uint32 index) const;
107           
108               /**
109                   Inserts a LanguageTag and quality value into the AcceptLanguageList
110                   object.  The element is inserted in order of descending quality value
111                   and after any other elements with the same quality value.
112                   @param languageTag The LanguageTag to insert.
113                   @param qualityValue The quality value to insert.
114                */
115               void insert(
116                   const LanguageTag& languageTag,
117                   Real32 qualityValue);
118           
119               /**
120                   Removes the specified LanguageTag and quality value from the 
121                   AcceptLanguageList object.
122                   @param index Integer index of the element to remove.
123                   @exception IndexOutOfBoundsException If the specified index is out of
124                   range.
125                */
126               void remove(Uint32 index);
127 kumpf 1.1 
128               /**
129                   Finds the first occurrence of the specified LanguageTag in the
130                   AcceptLanguageList object and returns its index.
131                   @param languageTag The LanguageTag to find.
132                   @return Integer index of the element, if found; otherwise
133                   PEG_NOT_FOUND.
134                */
135               Uint32 find(const LanguageTag& languageTag) const;
136           
137               /**
138                   Removes all the LanguageTags and quality values from the
139                   AcceptLanguageList object.
140                */
141               void clear();
142           
143               /**
144                   Tests AcceptLanguageList objects for equality.
145                   @param acceptLanguages An AcceptLanguageList object to be compared.
146                   @return True if the AcceptLanguageList objects contain the same
147                   LanguageTags and quality values in the same order, false otherwise.
148 kumpf 1.1      */
149               Boolean operator==(const AcceptLanguageList& acceptLanguages) const;
150           
151               /**
152                   Tests AcceptLanguageList objects for inequality.
153                   @param acceptLanguages An AcceptLanguageList object to be compared.
154                   @return False if the AcceptLanguageList objects contain the same
155                   LanguageTags and quality values in the same order, true otherwise.
156                */
157               Boolean operator!=(const AcceptLanguageList& acceptLanguages) const;
158           
159           private:
160               AcceptLanguageListRep* _rep;
161           };
162           
163           PEGASUS_NAMESPACE_END
164           
165           #endif  // PEGASUS_USE_EXPERIMENTAL_INTERFACES
166           
167           #endif