1 /*

     2 * Copyright (c) 2001-2006 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  EAP and WLAN authentication protocols.

    15 *

    16 */

    17 

    18 

    19 

    20 

    21 #if !defined(_EAP_VARIABLE_DATA_H_)

    22 #define _EAP_VARIABLE_DATA_H_

    23 

    24 #include "eap_am_types.h"

    25 #include "eap_am_export.h"

    26 //#include "eap_am_memory.h"

    27 #include "eap_am_assert.h"

    28 #include "eap_status.h"

    29 

    30 //--------------------------------------------------

    31 

    32 class abs_eap_am_tools_c;

    33 

    34 

    35 /// This class stores any data in byte array.

    36 class EAP_EXPORT eap_variable_data_c

    37 {

    38 private:

    39 	//--------------------------------------------------

    40 

    41 	/// This is pointer to the tools class. @see abs_eap_am_tools_c

    42 	abs_eap_am_tools_c * const m_am_tools;

    43 

    44 	/// This struct decreases the memory print of eap_variable_data_c.

    45 	struct eap_variable_data_impl_str

    46 	{

    47 		/// This is pointer to the buffer.

    48 		u8_t *m_buffer;

    49 

    50 		/// This indicates the length of the buffer.

    51 		u32_t m_buffer_length;

    52 

    53 		/// This indicates the start of the data in the buffer.

    54 		u32_t m_real_data_start_index;

    55 

    56 		/// This indicates the length of data in the buffer.

    57 		u32_t m_real_data_length;

    58 

    59 		/// This indicates the buffer is initialized. The attribute m_buffer points 

    60 		/// to a memory buffer which length is m_buffer_length bytes.

    61 		bool m_is_valid;

    62 

    63 		/// This indicates the buffer will be freed in destructor.

    64 		bool m_free_buffer;

    65 

    66 		/// This indicates the buffer pointed by m_buffer can be modified.

    67 		bool m_is_writable;

    68 	};

    69 

    70 	/// This is pointer to data of eap_variable_data_c.

    71 	/// This decreases memory print of eap_variable_data_c.

    72 	/// This decreases stack usage of EAP_Core.

    73 	eap_variable_data_impl_str *  m_data;

    74 

    75 

    76 	EAP_FUNC_IMPORT eap_status_e initialize_members();

    77 

    78 	EAP_FUNC_IMPORT eap_status_e allocate_buffer(

    79 		const u32_t required_buffer_length);

    80 

    81 	//--------------------------------------------------

    82 protected:

    83 	//--------------------------------------------------

    84 

    85 	//--------------------------------------------------

    86 public:

    87 	//--------------------------------------------------

    88 

    89 	/**

    90 	 * Destructor of the eap_variable_data class will release 

    91 	 * the buffer if attribute m_free_buffer is true.

    92 	 */

    93 	EAP_FUNC_IMPORT virtual ~eap_variable_data_c();

    94 

    95 	/**

    96 	 * Constructor takes only one parameter called tools.

    97 	 * @param tools is pointer to the tools class. @see abs_eap_am_tools_c.

    98 	 */

    99 	EAP_FUNC_IMPORT eap_variable_data_c(

   100 		abs_eap_am_tools_c * const tools);

   101 

   102 	/**

   103 	 * Constructor takes five parameters.

   104 	 * @param tools is pointer to the tools class. @see abs_eap_am_tools_c.

   105 	 * @param buffer is pointer to the buffer.

   106 	 * @param buffer_length is size of the buffer.

   107 	 * @param free_buffer indicates whether the buffer must be freed in the destructor.

   108 	 * @param is_writable indicates whether the buffer is writable.

   109 	 */

   110 	EAP_FUNC_IMPORT eap_variable_data_c(

   111 		abs_eap_am_tools_c * const tools,

   112 		const void * const buffer,

   113 		const u32_t buffer_length,

   114 		bool free_buffer,

   115 		bool is_writable);

   116 

   117 

   118 	/**

   119 	 * The get_is_valid() function returns the status of the eap_variable_data object.

   120 	 * @return True indicates the object is initialized.

   121 	 */

   122 	EAP_FUNC_IMPORT bool get_is_valid() const;

   123 

   124 

   125 	/**

   126 	 * The get_is_valid_data() function returns the status of the

   127 	 * data included in eap_variable_data object.

   128 	 * Note the object may include zero length data, and that is valid data.

   129 	 * @return True indicates the object includes valid data.

   130 	 */

   131 	EAP_FUNC_IMPORT bool get_is_valid_data() const;

   132 

   133 	/**

   134 	 * The set_is_valid() function sets the state of the eap_variable_data object valid.

   135 	 * The eap_variable_data_c object calls this function after it is initialized.

   136 	 */

   137 	EAP_FUNC_IMPORT void set_is_valid();

   138 

   139 	/**

   140 	 * The set_is_invalid() function sets the state of the eap_variable_data object invalid.

   141 	 * The eap_variable_data_c object calls this function after it is uninitialized.

   142 	 */

   143 	EAP_FUNC_IMPORT void set_is_invalid();

   144 

   145 	/**

   146 	 * This function returns flag that indicates whether this

   147 	 * buffer is writeble (true) or read only (false).

   148 	 */

   149 	EAP_FUNC_IMPORT bool get_is_writable() const;

   150 

   151 	/**

   152 	 * The get_data_offset() function returns the pointer to the buffer.

   153 	 * @param offset is offset from the begin of the buffer.

   154 	 * @param buffer_length is required count of bytes.

   155 	 */

   156 	EAP_FUNC_IMPORT u8_t * get_buffer_offset(

   157 		const u32_t offset,

   158 		const u32_t buffer_length) const;

   159 

   160 	/**

   161 	 * The get_buffer() function returns the pointer to the buffer.

   162 	 */

   163 	EAP_FUNC_IMPORT u8_t * get_buffer(const u32_t buffer_length) const;

   164 

   165 	/**

   166 	 * The get_data_offset() function returns the pointer to the data.

   167 	 * @param offset is offset from the begin of the data.

   168 	 * @param data_length is required count of bytes.

   169 	 */

   170 	EAP_FUNC_IMPORT u8_t * get_data_offset(

   171 		const u32_t offset,

   172 		const u32_t data_length) const;

   173 

   174 	/**

   175 	 * The get_data() function returns the pointer to the begin of the data.

   176 	 */

   177 	EAP_FUNC_IMPORT u8_t * get_data(const u32_t data_length) const;

   178 

   179 

   180 	/**

   181 	 * The get_data() function returns the pointer to the begin of the data.

   182 	 * This function assumes the whole data is needed.

   183 	 * User should test the validity of object and the length of the data before use of it.

   184 	 * The purpose of this function is reduce code size.

   185 	 */

   186 #if defined(USE_EAP_INLINE_FUNCTIONS)

   187 	EAP_INLINE u8_t * get_data() const

   188 	{

   189 

   190 #if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   191 		if (m_data != 0

   192 			&& m_data->m_is_valid == true)

   193 		{

   194 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   195 

   196 			return m_data->m_buffer + m_data->m_real_data_start_index;

   197 

   198 #if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   199 		}

   200 		else

   201 		{

   202 			return 0;

   203 		}

   204 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   205 

   206 	}

   207 

   208 #else

   209 

   210 	EAP_FUNC_IMPORT u8_t * get_data() const;

   211 

   212 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS)

   213 

   214 

   215 	/**

   216 	 * The get_data_length() function returns the count of bytes stored to the buffer.

   217 	 */

   218 #if defined(USE_EAP_INLINE_FUNCTIONS)

   219 	EAP_INLINE u32_t get_data_length() const

   220 	{

   221 

   222 #if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   223 		if (m_data != 0

   224 			&& m_data->m_is_valid == true)

   225 		{

   226 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   227 

   228 			return m_data->m_real_data_length;

   229 

   230 #if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   231 		}

   232 		else

   233 		{

   234 			return 0u;

   235 		}

   236 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   237 

   238 	}

   239 

   240 #else

   241 

   242 	EAP_FUNC_IMPORT u32_t get_data_length() const;

   243 

   244 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS)

   245 

   246 

   247 	/**

   248 	 * The get_buffer_length() function returns the size of the buffer.

   249 	 */

   250 #if defined(USE_EAP_INLINE_FUNCTIONS)

   251 

   252 	EAP_INLINE u32_t get_buffer_length() const

   253 	{

   254 

   255 #if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   256 		if (m_data != 0

   257 			&& m_data->m_is_valid == true)

   258 		{

   259 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   260 

   261 			return m_data->m_buffer_length;

   262 

   263 #if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   264 		}

   265 		else

   266 		{

   267 			return 0u;

   268 		}

   269 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS_RUNTIME_CHECKS)

   270 

   271 	}

   272 

   273 #else

   274 

   275 	EAP_FUNC_IMPORT u32_t get_buffer_length() const;

   276 

   277 #endif //#if defined(USE_EAP_INLINE_FUNCTIONS)

   278 

   279 

   280 	/**

   281 	 * The reset_start_offset_and_data_length() function sets the begin offset of the data to zero

   282 	 * and the length of data to zero.

   283 	 */

   284 	EAP_FUNC_IMPORT eap_status_e reset_start_offset_and_data_length();

   285 

   286 	/**

   287 	 * The set_start_offset() function sets the begin offset of the data to index.

   288 	 * With this function data in the begin of the buffer can be removed

   289 	 * without any copy operations.

   290 	 */

   291 	EAP_FUNC_IMPORT eap_status_e set_start_offset(const u32_t index);

   292 

   293 	/**

   294 	 * The set_data_length() function changes the length of the data.

   295 	 * @param length is count of bytes in the buffer.

   296 	 */

   297 	EAP_FUNC_IMPORT eap_status_e set_data_length(

   298 		const u32_t length);

   299 

   300 	/**

   301 	 * The set_buffer() function initializes the eap_variable_data object

   302 	 * using existing buffer.

   303 	 * @param buffer is pointer to the buffer.

   304 	 * @param buffer_length is size of the buffer.

   305 	 * @param free_buffer indicates whether the buffer must be freed in the destructor.

   306 	 * @param is_writable indicates whether the buffer is writable.

   307 	 */

   308 	EAP_FUNC_IMPORT eap_status_e set_buffer(

   309 		const void * const buffer,

   310 		const u32_t buffer_length,

   311 		bool free_buffer,

   312 		bool is_writable);

   313 

   314 	/**

   315 	 * The set_buffer() function initializes the eap_variable_data object

   316 	 * using existing buffer.

   317 	 * @param buffer is pointer to the buffer.

   318 	 * @param buffer_length is size of the buffer.

   319 	 * @param free_buffer indicates whether the buffer must be freed in the destructor.

   320 	 * @param is_writable indicates whether the buffer is writable.

   321 	 */

   322 	EAP_FUNC_IMPORT eap_status_e set_buffer(

   323 		void * const buffer,

   324 		const u32_t buffer_length,

   325 		bool free_buffer,

   326 		bool is_writable);

   327 

   328 	/**

   329 	 * The set_buffer() function initializes the eap_variable_data object

   330 	 * using existing buffer. Note the data will be in the same buffer.

   331 	 * Data can be modified through both eap_variable_data objects.

   332 	 * @param buffer is pointer to the buffer.

   333 	 */

   334 	EAP_FUNC_IMPORT eap_status_e set_buffer(

   335 		const eap_variable_data_c * const buffer);

   336 

   337 	/**

   338 	 * The set_copy_of_buffer() function copies the data of the buffer.

   339 	 * @param buffer points the data to be copied.

   340 	 * @param buffer_length is length of the buffer in bytes.

   341 	 */

   342 	EAP_FUNC_IMPORT eap_status_e set_copy_of_buffer(

   343 		const void * const buffer,

   344 		const u32_t buffer_length);

   345 

   346 	/**

   347 	 * The set_copy_of_buffer() function copies the data of the buffer.

   348 	 * The first version copies data pointed by parameter buffer.

   349 	 * @param buffer points the data to be copied.

   350 	 */

   351 	EAP_FUNC_IMPORT eap_status_e set_copy_of_buffer(

   352 		const eap_variable_data_c * const buffer);

   353 

   354 	/**

   355 	 * The set_buffer_length() function sets length ot the buffer

   356 	 * atleast to buffer_length bytes.

   357 	 * If the buffer is empty or less than buffer_length bytes, length of the buffer is set to buffer_length bytes.

   358 	 * If the buffer includes data, data is kept in the buffer.

   359 	 * @param buffer points the data to be added.

   360 	 * @param buffer_length is length of the buffer in bytes.

   361 	 */

   362 	EAP_FUNC_IMPORT eap_status_e set_buffer_length(

   363 		const u32_t buffer_length);

   364 

   365 	/**

   366 	 * The add_data() function adds data to the end of the buffer.

   367 	 * If the buffer is empty the data is added to begin of the buffer.

   368 	 * @param buffer points the data to be added.

   369 	 * @param buffer_length is length of the buffer in bytes.

   370 	 */

   371 	EAP_FUNC_IMPORT eap_status_e add_data(

   372 		const void * const buffer,

   373 		const u32_t buffer_length);

   374 

   375 	/**

   376 	 * The add_data() function adds data to the end of the buffer.

   377 	 * If the buffer is empty the data is added to begin of the buffer.

   378 	 * @param buffer points the data to be added.

   379 	 */

   380 	EAP_FUNC_IMPORT eap_status_e add_data(

   381 		const eap_variable_data_c * const buffer);

   382 

   383 	/**

   384 	 * The add_data_to_offset() function adds data to the offset of the buffer.

   385 	 * @param offset tells the place where data will begin.

   386 	 * @param buffer points the data to be added.

   387 	 * @param buffer_length is length of the buffer in bytes.

   388 	 */

   389 	EAP_FUNC_IMPORT eap_status_e add_data_to_offset(

   390 		const u32_t offset,

   391 		const void * const buffer,

   392 		const u32_t buffer_length);

   393 

   394 	/**

   395 	 * The add_data() function adds data to the offset of the buffer.

   396 	 * @param offset tells the place where data will begin.

   397 	 * @param buffer points the data to be added.

   398 	 */

   399 	EAP_FUNC_IMPORT eap_status_e add_data_to_offset(

   400 		const u32_t offset,

   401 		const eap_variable_data_c * const buffer);

   402 

   403 	/**

   404 	 * The add_end_null() function adds 16-bit null ('\0\0') to the end of the buffer.

   405 	 * This does not increase the data length.

   406 	 * This function is usefull when null terminated strings are stored to

   407 	 * eap_variable_data_c object.

   408 	 */

   409 	EAP_FUNC_IMPORT eap_status_e add_end_null();

   410 

   411 	/**

   412 	 * The reset() function resets the eap_variable_data object.

   413 	 * Memory of the buffer is freed if the m_free_buffer attribute is true.

   414 	 * Object does not include data after this call and get_is_valid_data()

   415 	 * returns false.

   416 	 */

   417 	EAP_FUNC_IMPORT eap_status_e reset();

   418 

   419 	/**

   420 	 * The init() function initializes the eap_variable_data object.

   421 	 * @param length is length of buffer in bytes that is allocated.

   422 	 * Buffer is set empty, data length is set zero.

   423 	 */

   424 	EAP_FUNC_IMPORT eap_status_e init(

   425 		const u32_t length);

   426 

   427 	/**

   428 	 * The copy() function copies the eap_variable_data object and data.

   429 	 */

   430 	EAP_FUNC_IMPORT eap_variable_data_c * copy() const;

   431 

   432 

   433 	/**

   434 	 * The compare_length() function compares first compare_length bytes of the objects.

   435 	 * @return Function returns zero when first compare_length bytes of the data are equal.

   436 	 * If the data of the caller object is shorter than compare_length bytes

   437 	 * or the first different byte of the caller is smaller the function returns negative value.

   438 	 * If the data of the parameter object is shorter than compare_length bytes

   439 	 * or the first different byte of the caller is larger the function returns positive value.

   440 	 */

   441 	EAP_FUNC_IMPORT i32_t compare_length(

   442 		const void * const data,

   443 		const u32_t data_length,

   444 		const u32_t compare_length_of_data) const;

   445 

   446 	/**

   447 	 * The compare_length() function compares first compare_length bytes of the objects.

   448 	 * @return Function returns zero when first compare_length bytes of the data are equal.

   449 	 * If the data of the caller object is shorter than compare_length bytes

   450 	 * or the first different byte of the caller is smaller the function returns negative value.

   451 	 * If the data of the parameter object is shorter than compare_length bytes

   452 	 * or the first different byte of the caller is larger the function returns positive value.

   453 	 */

   454 	EAP_FUNC_IMPORT i32_t compare_length(

   455 		const eap_variable_data_c * const data,

   456 		const u32_t compare_length_of_data) const;

   457 

   458 	/**

   459 	 * The compare() function compares the objects.

   460 	 * @return Function returns zero when data lengths and the data are equal.

   461 	 * If the data of the caller object is shorter or the first different byte

   462 	 * of the caller is smaller the function returns negative value.

   463 	 * If the data of the caller object is longer or the first different byte

   464 	 * of the caller is larger the function returns positive value.

   465 	 */

   466 	EAP_FUNC_IMPORT i32_t compare(

   467 		const void * const data,

   468 		const u32_t data_length) const;

   469 

   470 	/**

   471 	 * The compare() function compares the objects.

   472 	 * @return Function returns zero when data lengths and the data are equal.

   473 	 * If the data of the caller object is shorter or the first different byte

   474 	 * of the caller is smaller the function returns negative value.

   475 	 * If the data of the caller object is longer or the first different byte

   476 	 * of the caller is larger the function returns positive value.

   477 	 */

   478 	EAP_FUNC_IMPORT i32_t compare(

   479 		const eap_variable_data_c * const data) const;

   480 

   481 

   482 	/**

   483 	 * The hash() function returns HASH-value calculated from the data.

   484 	 * @return Maximum returned value is size-1. Minimum returned value is zero.

   485 	 */

   486 	EAP_FUNC_IMPORT u32_t hash(

   487 		const u32_t size) const;

   488 

   489 	//--------------------------------------------------

   490 }; // class eap_variable_data_c

   491 

   492 

   493 #endif //#if !defined(_EAP_VARIABLE_DATA_H_)

   494 

   495 // End.