1 dl.meetei 1.1 //%LICENSE////////////////////////////////////////////////////////////////
  2               //
  3               // Licensed to The Open Group (TOG) under one or more contributor license
  4               // agreements.  Refer to the OpenPegasusNOTICE.txt file distributed with
  5               // this work for additional information regarding copyright ownership.
  6               // Each contributor licenses this file to you under the OpenPegasus Open
  7               // Source License; you may not use this file except in compliance with the
  8               // License.
  9               //
 10               // Permission is hereby granted, free of charge, to any person obtaining a
 11               // copy of this software and associated documentation files (the "Software"),
 12               // to deal in the Software without restriction, including without limitation
 13               // the rights to use, copy, modify, merge, publish, distribute, sublicense,
 14               // and/or sell copies of the Software, and to permit persons to whom the
 15               // Software is furnished to do so, subject to the following conditions:
 16               //
 17               // The above copyright notice and this permission notice shall be included
 18               // in all copies or substantial portions of the Software.
 19               //
 20               // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 21               // OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 22 dl.meetei 1.1 // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 23               // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 24               // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 25               // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 26               // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 27               //
 28               //////////////////////////////////////////////////////////////////////////
 29               //
 30               //%/////////////////////////////////////////////////////////////////////////////
 31               
 32               #ifndef Pegasus_IndicationFormatter_h
 33               #define Pegasus_IndicationFormatter_h
 34               
 35               #include <Pegasus/Common/Config.h>
 36               #include <Pegasus/Common/String.h>
 37               #include <Pegasus/Common/Array.h>
 38               #include <Pegasus/Common/CIMInstance.h>
 39               #include <Pegasus/Common/CIMClass.h>
 40               #include <Pegasus/Common/CIMValue.h>
 41               #include <Pegasus/Common/CIMPropertyList.h>
 42               #include <Pegasus/Common/ContentLanguageList.h>
 43 dl.meetei 1.1 
 44               #include <Pegasus/Handler/Linkage.h>
 45               
 46               PEGASUS_NAMESPACE_BEGIN
 47               
 48               /**
 49                   The IndicationFormatter class formats an indication message.
 50               */
 51               class PEGASUS_HANDLER_LINKAGE IndicationFormatter
 52               {
 53               public:
 54               
 55                   /**
 56                       Based on subscription instance, gets the formatted indication text
 57                       message from the received indication instance.
 58               
 59                       @param   subscription   the subscription instance
 60                       @param   indication     the received indication instance
 61                       @param   contentLangs   the Content-Languages in the
 62                                               subscription instance
 63               
 64 dl.meetei 1.1         @return  String containing the formatted indication text message
 65                   */
 66                   static String getFormattedIndText(
 67                       const CIMInstance& subscription,
 68                       const CIMInstance& indication,
 69                       const ContentLanguageList& contentLangs);
 70               
 71               
 72                   /**
 73                       Validates the syntax and the provided type for the property
 74                       TextFormat in the instance.
 75                       If the value of the property has a syntax error, or the
 76                       provided type does not match the property type,
 77                       an exception is thrown.
 78               
 79                       This function is called by the _canCreate function, and is used to
 80                       validate the syntax and the provided type for the property
 81                       TextFormat in the Formatted Subscription instance.
 82               
 83                       @param   textFormatStr     the string to be validated
 84                       @param   indicationClass   the indication class
 85 dl.meetei 1.1         @param   textFormatParams  the value of the TextFormatParameters
 86               
 87                       @throw   CIM_ERR_INVALID_PARAMETER  if there is a syntax error
 88                                                           for the value of property
 89                                                           TextFormat or type mismatch
 90                    */
 91                   static void validateTextFormat(
 92                       const String& textFormatStr,
 93                       const CIMClass& indicationClass,
 94                       const Array<String>& textFormatParams);
 95               
 96                   /**
 97                       Validates the value of the property TextFormatParameters in the
 98                       subscriptionInstance.
 99                       If the property name in the TextFormatParameters is not the name
100                       contained in the select clause of the associated filter query
101                       in the filterInstance, an exception is thrown.
102               
103                       @param   propertyList        the list of properties to be validated
104                       @param   indicationClass     the indication class
105                       @param   textFormatParams    the value of the property
106 dl.meetei 1.1                                      TextFormatParameters
107               
108                       @throw   CIM_ERR_INVALID_PARAMETER  if the select clause of the
109                                                           filter query does not contain
110                                                           the provided property name
111                    */
112                   static void validateTextFormatParameters(
113                       const CIMPropertyList& propertyList,
114                       const CIMClass& indicationClass,
115                       const Array<String>& textFormatParams);
116               
117               private:
118               
119                   /**
120                       Gets a specified indication property value from an indication instance.
121               
122                       @param propertyName The name of the property for which to get the value.
123                       @param arrayIndex The array index of the value to get, if the property
124                           has an array value.  A value of PEG_NOT_FOUND indicates that all
125                           array values are requested.
126                       @param indication The indication from which to get the property value.
127 dl.meetei 1.1         @param contentLangs The language in which to encode the value.
128                       @return String containing property value
129                   */
130                   static String _getIndPropertyValue(
131                       const String& propertyName,
132                       Uint32 arrayIndex,
133                       const CIMInstance& indication,
134                       const ContentLanguageList& contentLangs);
135               
136                   /**
137                       Retrieves the array values contained by the specified CIMValue.
138               
139                       @param value The CIMValue from which to get the array values.
140                       @param arrayIndex The array index for which to get the value.  A value
141                           of PEG_NOT_FOUND indicates that all values are requested.
142                       @param contentLangs The language in which to encode the value.
143                       @return String containing array values contained by the CIMValue.
144                   */
145                   static String _getArrayValues(
146                       const CIMValue& value,
147                       Uint32 arrayIndex,
148 dl.meetei 1.1         const ContentLanguageList& contentLangs);
149               
150                   /**
151                       Parses an index value from a string.  The string must represent an
152                       unsigned integer.  Leading and trailing whitespace is ignored.
153               
154                       @param indexStr The string from which to parse the index.
155                       @throw CIM_ERR_INVALID_PARAMETER If the string is improperly formatted.
156                    */
157                   static Uint32 _parseIndex(const String& indexStr);
158               
159                   /**
160                       Trims leading and trailing whitespace from a String.
161                       @param s The string from which to trim whitespace.
162                   */
163                   static void _trim(String& s);
164               
165                   /**
166                       Validates the provided property type string.
167                       If the provided property type does not match the type of the property,
168                       or the provided property type is not valid type, or the dynamic
169 dl.meetei 1.1         content with an array index refers to a non array type, an
170                       exception is thrown.
171               
172                       This function is called by the _validatePropertySyntaxAndType
173                       function, and is used to validate the provided property type.
174               
175                       @param   indicationClass   the indication class
176                       @param   propertyParam     the provided property
177                       @param   propertyTypeStr   the provided property type
178                       @param   isArray           indicates whether refers to an array type
179               
180                       @throw   CIM_ERR_INVALID_PARAMETER  if the provided property type is
181                                                           unexpected
182                    */
183                   static void _validatePropertyType(
184                       const CIMClass& indicationClass,
185                       const String& propertyParam,
186                       const String& propertyTypeStr,
187                       const Boolean& isArray);
188               
189                   /**
190 dl.meetei 1.1         Constructs a default indication text message from the received
191                       indication instance.
192               
193                       @param   indication     the received indication instance
194                       @param   contentLangs   the Content-Languages in the
195                                               subscription instance
196               
197                       @return  String containing default indication text message
198                   */
199                   static String _formatDefaultIndicationText(
200                       const CIMInstance& indication,
201                       const ContentLanguageList& contentLangs);
202               
203                   /**
204                       Constructs a human readable indication text message from the
205                       specified indication textFormat, textFormatParams, and
206                       received indication instance.
207               
208                       @param   textFormat        the specified indication textFormat
209                       @param   textFormatParams  the indexed array containing the names
210                                                  of properties defined in the select
211 dl.meetei 1.1                                    clause of the associated
212                                                  CIM_IndicationFilter Query
213                       @param   indication        the received indication instance
214                       @param   contentLangs      the Content-Languages in the
215                                                  subscription instance
216               
217                       @return  String containing a human readable indication text message
218                   */
219                   static String _formatIndicationText(
220                       const String& textFormat,
221                       const Array<String>& textFormatParams,
222                       const CIMInstance& indication,
223                       const ContentLanguageList& contentLangs);
224               };
225               
226               PEGASUS_NAMESPACE_END
227               
228               #endif /* Pegasus_IndicationFormatter_h */