fds.h

00001 /*
00002  * Copyright (c) Nordic Semiconductor ASA
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  *
00008  *   1. Redistributions of source code must retain the above copyright notice, this
00009  *   list of conditions and the following disclaimer.
00010  *
00011  *   2. Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  *
00015  *   3. Neither the name of Nordic Semiconductor ASA nor the names of other
00016  *   contributors to this software may be used to endorse or promote products
00017  *   derived from this software without specific prior written permission.
00018  *
00019  *
00020  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00021  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00022  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00023  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00024  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00025  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00026  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00027  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00028  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  *
00031  */
00032 
00033 #ifndef FDS_H__
00034 #define FDS_H__
00035 
00036 /**
00037  * @defgroup flash_data_storage Flash Data Storage
00038  * @ingroup app_common
00039  * @{
00040  * @brief Flash Data Storage (FDS).
00041  *
00042  * @details Flash Data Storage (FDS) is a minimalistic filesystem for the on-chip flash.
00043  *          It can be used to manipulate @e records, which consist of a piece of data, made up
00044  *          of one or more chunks, and an associated key pair. 
00045  */
00046 
00047 #include <stdint.h>
00048 #include <stdbool.h>
00049 #include "sdk_errors.h "
00050 
00051 
00052 /**@brief */
00053 #define SIZEOF_WORDS(val)       (sizeof(val) / 4)
00054 
00055 /**@brief Reserved type key used to flag cleared records.
00056  *        May not be used as a record key by the application. */
00057 #define FDS_TYPE_ID_INVALID     (0x0000)
00058 /**@brief Reserved instance key used to check for missing or corrupted metadata.
00059  *        May not be used as a record key by the application. */
00060 #define FDS_INSTANCE_ID_INVALID (0xFFFF)
00061 
00062 
00063 typedef uint32_t fds_record_id_t;
00064 typedef uint16_t fds_type_id_t;
00065 typedef uint16_t fds_length_t;
00066 typedef uint16_t fds_instance_id_t;
00067 typedef uint16_t fds_checksum_t;
00068 
00069 
00070 /**@brief A piece of a record metadata, keeping information about one of its keys (type) and its
00071  *        lenght, expressed in 4 byte words. */
00072 typedef struct 
00073 {
00074     fds_type_id_t type;           /**< The record type ID. */
00075     fds_length_t  length_words;   /**< Length of the record's data, in 4 byte words. */
00076 } fds_tl_t;
00077 
00078 
00079 /**@brief A piece of a record metadata, keeping information about one of its keys (instance) and
00080  *        its checksum. */
00081 typedef struct
00082 {
00083     fds_instance_id_t instance;       /**< The record instance ID. */
00084     fds_checksum_t    checksum;       /**< Checksum of the entire record, including the metadata. */
00085 } fds_ic_t;
00086 
00087 
00088 /**@brief The record metadata. */
00089 typedef struct
00090 {
00091     fds_tl_t        tl;     /**< See @ref fds_tl_t. */
00092     fds_ic_t        ic;     /**< See @ref fds_ic_t. */
00093     fds_record_id_t id;     /**< The unique record ID (32 bits). */
00094 } fds_header_t;
00095 
00096 
00097 typedef fds_header_t fds_record_header_t;
00098 
00099 /**@brief The record descriptor structure, used to manipulate a record.
00100  * @note  This structure is meant to be opaque to the user, who does not need to access
00101  *        any of its fields.
00102  * @note    This structure does not need special initialization.
00103  * @warning Do not reuse the same descriptor for different records. If you do, be sure to set
00104  *          its fields to zero. */
00105 typedef struct
00106 {
00107     uint32_t         record_id;     /**< The unique record ID. */
00108     uint32_t const * p_rec;         /**< The last known record address in flash. */
00109     uint16_t         vpage_id;      /**< The virtual page ID in which the record is stored. */
00110     uint16_t         gc_magic;      /**< Number of times the GC algorithm has been run. */
00111     uint16_t         ptr_magic;     /**< Used to verify the validity of p_rec. */
00112 } fds_record_desc_t;
00113 
00114 
00115 /**@brief The record key, used to lookup records.
00116  * @note  The uniqueness of either field is not enforced by the system. */
00117 typedef struct
00118 {
00119     uint16_t type;
00120     uint16_t instance;
00121 } fds_record_key_t;
00122 
00123 
00124 /**@brief Structure used for reading a record back from flash memory. */
00125 typedef struct
00126 {
00127     // TODO: the header should be a pointer.
00128     fds_header_t         header;        /**< The record header (metadata), as stored in flash. */
00129     uint32_t     const * p_data;        /**< The record data. */
00130 } fds_record_t;
00131 
00132 
00133 /**@brief A record chunk, containing a piece of data to be stored in a record.
00134  *
00135  * @note  p_data must be aligned on a (4 bytes) word boundary.
00136  */
00137 typedef struct
00138 {
00139     void         const * p_data;           /**< Pointer to the data to store. Must be word aligned. */
00140     fds_length_t         length_words;     /**< Length of data pointed by p_data, in 4 byte words. */
00141 } fds_record_chunk_t;
00142 
00143 
00144 /**@brief A token to a reserved space in flash, created by @ref fds_reserve.
00145  *        Use @ref fds_write_reserved to write the record in the reserved space,
00146  *        or @ref fds_reserve_cancel to cancel the reservation.
00147  */
00148 typedef struct
00149 {
00150     uint16_t            vpage_id;       /**< The virtual ID of the page where space was reserved. */
00151     fds_length_t        length_words;   /**< The amount of space reserved, in 4 byte words. */
00152 } fds_write_token_t;
00153 
00154 
00155 /**@brief A token to keep information about the progress of @ref fds_find, @ref fds_find_by_type
00156  *        and @ref fds_find_by_instance operations.
00157  * @note  This structure is meant to be opaque to the user, who does not need to access any of its
00158  *        fields.
00159  * @note  The token does not need special initialization.
00160  * @warning Do not reuse the same token to search for different records. If you do, be sure to set
00161  *          its fields to zero. */
00162 typedef struct
00163 {
00164     uint32_t const * p_addr;
00165     uint32_t         magic;
00166     uint16_t         vpage_id;
00167 } fds_find_token_t;
00168 
00169 
00170 typedef enum
00171 {
00172     FDS_CMD_NONE,       /**< No command. */
00173     FDS_CMD_INIT,       /**< Module initialization commnad. Used in @ref fds_init */
00174     FDS_CMD_WRITE,      /**< Write command. Used in @ref fds_write and @ref fds_write_reserved. */
00175     FDS_CMD_UPDATE,     /**< Update command. Used in @ref fds_update. */
00176     FDS_CMD_CLEAR,      /**< Clear record command. Used in @ref fds_clear and @ref fds_update. */
00177     FDS_CMD_CLEAR_INST, /**< Clear instance command. Used in @ref fds_clear_by_instance. */
00178     FDS_CMD_GC          /**< Garbage collection. Used in @ref fds_gc. */
00179 } fds_cmd_id_t ;
00180 
00181  
00182 /**@brief Flash data storage callback function.
00183  *
00184  * @param result     Result of the command.
00185  * @param cmd        The command associated with the callback.
00186  * @param record_id  The unique ID of the record associated with the callback.
00187  * @param record_key The key pair of the record associated with the callback.
00188  */
00189 typedef void (*fds_cb_t)(ret_code_t       result,
00190                          fds_cmd_id_t      cmd,
00191                          fds_record_id_t  record_id,
00192                          fds_record_key_t record_key);
00193 
00194 
00195 /**@brief       Function to register a callback for the module events.
00196  * @details     The maximum amount of callback which can be registered can be configured by
00197  *              changing the FDS_MAX_USERS macro in fds_config.h.
00198  * 
00199  * @param[in]   cb The callback function.
00200  *
00201  *
00202  * @retval      NRF_SUCCESS      Success.
00203  * @retval      NRF_ERROR_NO_MEM Error. Maximum number of registered callbacks reached.
00204  */
00205 ret_code_t fds_register(fds_cb_t cb);
00206 
00207 
00208 /**@brief Function to initialize the module.
00209  *
00210  * @details This function initializes the module and installs the filesystem, if it is not
00211  *          installed yet.
00212  *
00213  * @note    This function is asynchronous. Completion is reported with a callback through the
00214  *          registered event handler. To be able to receive such callback, be sure to call
00215  *          @ref fds_register before calling @ref fds_init.
00216  *
00217  * @retval  NRF_SUCCESS                 Success. The command was queued.
00218  * @retval  NRF_ERROR_INVALID_STATE     Error. The module is currently undergoing initialization.
00219  * @retval  NRF_ERROR_NO_MEM            Error. Insufficient space to install the filesystem, or
00220  *                                      insufficient resources to perform the installation.
00221  */
00222 ret_code_t fds_init(void);
00223 
00224 
00225 /**@brief Function to write a record to flash.
00226  *
00227  * @details This function can be used to write a record to flash. A record data consists of
00228  *          multiple chunks and is supplied to the function as an array of fds_record_chunk_t
00229  *          structures. The maximum lenght of a record data may not exceed the size of one flash
00230  *          page minus FDS_HEADER_SIZE words.
00231  *            
00232  * @note This function is asynchronous, therefore, completion is reported with a callback
00233  *       through the registered event handler.
00234  *
00235  * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered
00236  *       internally, it must be kept in memory by the application until the callback for the
00237  *       command has been received, i.e., the command completed.
00238  *
00239  * @param[out] p_desc     The record descriptor. It may be NULL.
00240  * @param[in]  key        The record key pair.
00241  * @param[in]  num_chunks The number of elements in the chunks array.
00242  * @param[in]  chunks     An array of chunks making up the record data.
00243  *
00244  * @retval NRF_SUCCESS               Success. The command was queued.
00245  * @retval NRF_ERROR_INVALID_STATE   Error. The module is not initialized.
00246  * @retval NRF_ERROR_INVALID_DATA    Error. The key contains an invalid type or instance.
00247  * @retval NRF_ERROR_INVALID_ADDR    Error. The record data is not aligned on a 4 byte boundary.
00248  * @retval NRF_ERROR_INVALID_LENGTH  Error. The record length exceeds the maximum lenght.
00249  * @retval NRF_ERROR_BUSY            Error. Insufficient internal resources to queue the operation.
00250  * @retval NRF_ERROR_NO_MEM          Error. No flash space available to store the record.
00251  */
00252 ret_code_t fds_write(fds_record_desc_t * const p_desc,
00253                      fds_record_key_t          key,
00254                      uint8_t                   num_chunks,
00255                      fds_record_chunk_t        chunks[]);
00256 
00257 
00258 /**@brief Function to reserve space for a record.
00259  *
00260  * @details This function can be used to reserve flash space to store a record, which can be
00261  *          later written down using @ref fds_write_reserved. It is possible to cancel a
00262  *          reservation by using @ref fds_reserve_cancel.
00263  *
00264  * @param[out] p_tok        A token which can be used to write a record in the reserved space
00265  *                          using @ref fds_write_reserved.
00266  * @param[in]  length_words The lenght of the record data, in 4 byte words.
00267  *
00268  * @retval  NRF_SUCCESS             Success. Flash space was successfully reserved.
00269  * @retval  NRF_ERROR_NULL          Error. p_tok is NULL.
00270  * @retval  NRF_ERROR_INVALID_STATE Error. The module is not initialized.
00271  * @retval  NRF_ERROR_NO_MEM        Error. Insufficient space.
00272  */
00273 ret_code_t fds_reserve(fds_write_token_t * const p_tok, uint16_t length_words);
00274 
00275 
00276 /**@brief Function to cancel a space reservation.
00277  *
00278  * @param[in] p_tok The token produced by @ref fds_reserve, identifying the reservation to cancel.
00279  *
00280  * @retval NRF_SUCCESS             Success. The reservation was canceled.
00281  * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
00282  * @retval NRF_ERROR_NULL          Error. p_tok is NULL.
00283  * @retval NRF_ERROR_INVALID_DATA  Error. p_tok contains invalid data.
00284  */
00285 ret_code_t fds_reserve_cancel(fds_write_token_t * const p_tok);
00286 
00287 
00288 /**@brief Function to write a record to flash, the space for which has been previously reserved
00289  *        using @ref fds_reserve.
00290  *
00291  * @details This function behaves similarly to @ref fds_write, with the exception that it never
00292  *          fails with NRF_ERROR_NO_MEM.
00293  *
00294  * @note This function is asynchronous, therefore, completion is reported with a callback
00295  *       through the registered event handler.
00296  *
00297  * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered
00298  *       internally, it must be kept in memory by the application until the callback for the
00299  *       command has been received, i.e., the command completed.
00300  *
00301  * @param[in]  p_tok      The token return by @ref fds_reserve.
00302  * @param[out] p_desc     The record descriptor. It may be NULL.
00303  * @param[in]  key        The record key pair.
00304  * @param[in]  num_chunks The number of elements in the chunks array.
00305  * @param[in]  chunks     An array of chunks making up the record data.
00306  *
00307  * @retval NRF_SUCCESS               Success. The command was queued.
00308  * @retval NRF_ERROR_INVALID_STATE   Error. The module is not initialized.
00309  * @retval NRF_ERROR_INVALID_DATA    Error. The key contains an invalid type or instance.
00310  * @retval NRF_ERROR_INVALID_ADDR    Error. The record data is not aligned on a 4 byte boundary.
00311  * @retval NRF_ERROR_INVALID_LENGTH  Error. The record length exceeds the maximum lenght.
00312  * @retval NRF_ERROR_BUSY            Error. Insufficient internal resources to queue the operation.
00313  */
00314 ret_code_t fds_write_reserved(fds_write_token_t  const * const p_tok,
00315                               fds_record_desc_t        * const p_desc,
00316                               fds_record_key_t                 key,
00317                               uint8_t                          num_chunks,
00318                               fds_record_chunk_t               chunks[]);
00319 
00320 
00321 /**@brief Function to clear a record.
00322  *
00323  * @details Clearing a record has the effect of preventing the system from retrieving the record
00324  *          descriptor using the @ref fds_find, @ref fds_find_by_type and @ref fds_find_by_instance
00325  *          functions. Additionally, @ref fds_open calls shall fail when supplied a descritpor for
00326  *          a record which has been cleared. Clearing a record does not free the space it occupies
00327  *          in flash. The reclaim flash space used by cleared records, use @ref fds_gc.
00328  *
00329  * @note    This function is asynchronous, therefore, completion is reported with a callback
00330  *          through the registered event handler.
00331  *
00332  * @param[in] p_desc The descriptor of the record to clear.
00333  *
00334  * @retval NRF_SUCCESS             Success. The command was queued.
00335  * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
00336  * @retval NRF_ERROR_NULL          Error. p_desc is NULL.
00337  * @retval NRF_ERROR_BUSY          Error. Insufficient internal resources to queue the operation.
00338  */
00339 ret_code_t fds_clear(fds_record_desc_t * const p_desc);
00340 
00341 
00342 /**@brief Function to clear all records with a given instance.
00343  *
00344  * @details Clearing a record has the effect of preventing the system from retrieving the record
00345  *          descriptor using the @ref fds_find, @ref fds_find_by_type and @ref fds_find_by_instance
00346  *          functions. Additionally, @ref fds_open calls shall fail when supplied a descritpor for
00347  *          a record which has been cleared. Clearing a record does not free the space it occupies
00348  *          in flash. The reclaim flash space used by cleared records, use @ref fds_gc.
00349  *
00350  * @note This function is asynchronous, therefore, completion is reported with a callback
00351  *       through the registered event handler. Only one callback will be issued. The record
00352  *       instance ID in the key parameter of the callback will contain the instance ID passed as
00353  *       parameter to this function. The record ID parameter will be zero, and the type ID equal
00354  *       to FDS_TYPE_ID_INVALID.
00355  *
00356  * @param[in] instance The instance ID of the records to clear.
00357  *
00358  * @retval NRF_SUCCESS             Success. The command was queued.
00359  * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
00360  * @retval NRF_ERROR_NULL          Error. p_desc is NULL.
00361  * @retval NRF_ERROR_BUSY          Error. Insufficient internal resources to queue the operation.
00362  */
00363 ret_code_t fds_clear_by_instance(fds_instance_id_t instance);
00364 
00365 
00366 /**@brief Function to update an existing record.
00367  *
00368  * @details Updating a record writes a new record with the given key and data in flash, and then
00369  *          clears the old record.
00370  *
00371  * @note This function is asynchronous, therefore, completion is reported with a callback
00372  *       through the registered event handler. Two callbacks will be issued, one to signal that
00373  *       the updated record has been written down, and another to signal that the old one has been
00374  *       cleared.
00375  *       
00376  * @note The record data must be aligned on a 4 byte boundary, and because it is not buffered
00377  *       internally, it must be kept in memory by the application until the callback for the
00378  *       command has been received, i.e., the command completed.
00379  * 
00380  * @param[in, out] p_desc The descriptor of the record to update. The descriptor of the updated
00381  *                        record, after the function has returned with NRF_SUCCESS.
00382  * @param[in] key         The record new key pair.
00383  * @param[in] num_chunks  The number of elements in the chunks array.
00384  * @param[in] chunks      An array of chunks making up the record new data.
00385  *
00386  * @retval NRF_SUCCESS               Success. The command was queued.
00387  * @retval NRF_ERROR_INVALID_STATE   Error. The module is not initialized.
00388  * @retval NRF_ERROR_INVALID_DATA    Error. The key contains an invalid type or instance.
00389  * @retval NRF_ERROR_INVALID_ADDR    Error. The record data is not aligned on a 4 byte boundary.
00390  * @retval NRF_ERROR_INVALID_LENGTH  Error. The record length exceeds the maximum lenght.
00391  * @retval NRF_ERROR_BUSY            Error. Insufficient internal resources to queue the operation.
00392  * @retval NRF_ERROR_NO_MEM          Error. No flash space available to store the record.
00393  */
00394 ret_code_t fds_update(fds_record_desc_t  * const p_desc,
00395                       fds_record_key_t           key,
00396                       uint8_t                    num_chunks,
00397                       fds_record_chunk_t         chunks[]);
00398 
00399 
00400 /**@brief Function to search for records with a given key pair.
00401  *
00402  * @details Because types are not unique, to search for the next record with the given key call
00403  *          the function again and supply the same fds_find_token_t structure to resume searching
00404  *          from the last record found.
00405  *
00406  * @param[in]  type     The record type ID.
00407  * @param[in]  instance The record instance ID.
00408  * @param[out] p_desc   The descriptor of the record found.
00409  * @param[out] p_token  A token containing information about the progress of the operation.
00410  *
00411  * @retval NRF_SUCCESS             Success. A record was found.
00412  * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
00413  * @retval NRF_ERROR_NULL          Error. Either p_desc or p_token are NULL.
00414  * @retval NRF_ERROR_NOT_FOUND     Error. No record with the given key pair was found.
00415  */
00416 ret_code_t fds_find(fds_type_id_t             type, 
00417                     fds_instance_id_t         instance, 
00418                     fds_record_desc_t * const p_desc,
00419                     fds_find_token_t  * const p_token);
00420 
00421 
00422 /**@brief Function to search for records with a given type.
00423  *
00424  * @details Because types are not unique, to search for the next record with the given key call
00425  *          the function again and supply the same fds_find_token_t structure to resume searching
00426  *          from the last record found.
00427  *
00428  * @param[in]  type    The type ID in the record key.
00429  * @param[out] p_desc  The descriptor of the record found.
00430  * @param[out] p_token A token containing information about the progress of the operation.
00431  *
00432  * @retval NRF_SUCCESS             Success. A record was found.
00433  * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
00434  * @retval NRF_ERROR_NULL          Error. Either p_desc or p_token are NULL.
00435  * @retval NRF_ERROR_NOT_FOUND     Error. No record with the given type was found.
00436  */
00437  ret_code_t fds_find_by_type(fds_type_id_t             type,
00438                              fds_record_desc_t * const p_desc,
00439                              fds_find_token_t  * const p_token);
00440 
00441 
00442 /**@brief Function to search for records with a given instance.
00443  *
00444  * @details Because types are not unique, to search for the next record with the given key call
00445  *          the function again and supply the same fds_find_token_t structure to resume searching
00446  *          from the last record found.
00447  *
00448  * @param[in]  instance The instance ID in the record key.
00449  * @param[out] p_desc   The descriptor of the record found.
00450  * @param[out] p_token  A token containing information about the progress of the operation.
00451  *
00452  * @retval NRF_SUCCESS             Success. A record was found.
00453  * @retval NRF_ERROR_INVALID_STATE Error. The module is not initialized.
00454  * @retval NRF_ERROR_NULL          Error. Either p_desc or p_token are NULL.
00455  * @retval NRF_ERROR_NOT_FOUND     Error. No record with the given instance was found.
00456  */
00457 ret_code_t fds_find_by_instance(fds_instance_id_t         instance,
00458                                 fds_record_desc_t * const p_desc,
00459                                 fds_find_token_t  * const p_token);
00460 
00461 
00462 /**@brief Function to open a record for reading.
00463  *
00464  * @details Function to read a record which has been written to flash. This function initializes
00465  *          a fds_record_t structure which can be used to access the record data as well as
00466  *          its associated metadata. The pointers provided in the fds_record_t structure are
00467  *          pointers to flash memory. Opening a record with @ref fds_open prevents the garbage
00468  *          collection to run on the flash page in which record is stored, therefore the contents
00469  *          of the memory pointed by the fds_record_t p_data field is guaranteed to remain
00470  *          unmodified, as long as the record is kept open.
00471  *
00472  * @note When you are done reading a record, close it using @ref fds_close so that successive
00473  *       garbage collections can reclaim space on the page where the record is stored, if necessary.
00474  *
00475  * @param[in]  p_desc   The descriptor of the record to open.
00476  * @param[out] p_record The record data and metadata, as stored in flash.
00477  *
00478  * @retval NRF_SUCCESS            Success. The record was opened.
00479  * @retval NRF_ERROR_NOT_FOUND    Error. The record was not found. It may have been cleared, or it
00480  *                                may have not been written yet.
00481  * @retval NRF_ERROR_INVALID_DATA Error. The descriptor contains invalid data.
00482  * @retval NRF_ERROR_NULL         Error. Either p_desc or p_record are NULL.
00483  */
00484 ret_code_t fds_open(fds_record_desc_t * const p_desc,
00485                     fds_record_t      * const p_record);
00486 
00487 
00488 /**@brief Function to close a record, after its contents have been read.
00489  *
00490  * @details Closing a record allows garbage collection to be run on the page in which the
00491  *          record being closed is stored (if no other records remain open on that page).
00492  *
00493  * @note Closing a record, does NOT invalidate its descriptor, which can be safely supplied to
00494  *       all functions which accept a descriptor as a parameter.
00495  *
00496  * @param[in] p_desc The descriptor of the record to close.
00497  *
00498  * @retval NRF_SUCCESS            Success. The record was closed.
00499  * @retval NRF_ERROR_NULL         Error. p_desc is NULL.
00500  * @retval NRF_ERROR_INVALID_DATA Error. The descriptor contains invalid data.
00501  */
00502 ret_code_t fds_close(fds_record_desc_t const * const p_desc);
00503 
00504 
00505 /**@brief Function to perform a garbage collection.
00506  *
00507  * @details Garbage collection reclaims the flash space occupied by records which have been cleared
00508  *          using @ref fds_clear.
00509  *
00510  * @note    This function is asynchronous, therefore, completion is reported with a callback
00511  *          through the registered event handler.
00512  */
00513 ret_code_t fds_gc(void);
00514 
00515 
00516 /**@brief Function to compare two record descriptors.
00517  *
00518  * @param[in] p_desc_one First descriptor.
00519  * @param[in] p_desc_two Second descriptor.
00520  *
00521  * @retval true  If the descriptors identify the same record.
00522  * @retval false Otherwise.
00523  */
00524 bool fds_descriptor_match(fds_record_desc_t const * const p_desc_one,
00525                           fds_record_desc_t const * const p_desc_two);
00526 
00527 
00528 /**@brief Function to obtain a descriptor from a record ID.
00529  *
00530  * @details This function can be used to reconstruct a descriptor from a record ID, such as the
00531  *          one passed to the callback function.
00532  *
00533  * @warning This function does not check if a record with the given record ID exists or not. If a
00534  *          non-existing record ID is supplied, the resulting descriptor will cause other functions
00535  *          to fail when used as parameter.
00536  *
00537  * @param[out] p_desc    The descriptor of the record with given record ID.
00538  * @param[in]  record_id The record ID for which to provide a descriptor.
00539  *
00540  * @retval NRF_SUCCESS         Success.
00541  * @retval NRF_ERROR_NULL      Error. p_desc is NULL.
00542  */
00543 ret_code_t fds_descriptor_from_rec_id(fds_record_desc_t * const p_desc,
00544                                       fds_record_id_t           record_id);
00545 
00546 /**@brief Function to obtain a record ID from a record descriptor.
00547  *
00548  * @details This function can be used to extract a record ID from a descriptor. It may be used
00549  *          in the callback function to determine which record the callback is associated to, if
00550  *          you have its descriptor.
00551  *
00552  * @warning This function does not check the record descriptor sanity. If the descriptor is
00553  *          uninitialized, or has been tampered with, the resulting record ID may be invalid.
00554  *
00555  * @param[in]  p_desc      The descriptor from which to extract the record ID.
00556  * @param[out] p_record_id The record ID contained in the given descriptor.
00557  *
00558  * @retval NRF_SUCCESS    Success.
00559  * @retval NRF_ERROR_NULL Error. Either p_desc is NULL or p_record_id is NULL.
00560  */
00561 ret_code_t fds_record_id_from_desc(fds_record_desc_t const * const p_desc,
00562                                    fds_record_id_t         * const p_record_id);
00563 
00564 /** @} */
00565                                          
00566 #endif // FDS_H__