peer_id.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 
00034 #ifndef PEER_ID_H__
00035 #define PEER_ID_H__
00036 
00037 
00038 #include "stdint.h"
00039 #include "sdk_errors.h "
00040 #include "ble_gap.h"
00041 #include "peer_manager_types.h "
00042 
00043 
00044 /**
00045  * @defgroup peer_id Peer IDs
00046  * @ingroup peer_manager
00047  * @{
00048  * @brief An internal module of @ref peer_manager. This module keeps track of which peer IDs are in
00049  *        use and which are free.
00050  */
00051 
00052 
00053 /**@brief Function for initializing the module.
00054  */
00055 void peer_id_init(void);
00056 
00057 
00058 /**@brief Function for claiming an unused peer ID.
00059  *
00060  * @param peer_id  The peer ID to allocate. If this is @ref PM_PEER_ID_INVALID, the first available
00061  *                 will be allocated.
00062  *
00063  * @return  The allocated peer ID.
00064  * @retval  PM_PEER_ID_INVALID  If no peer ID could be allocated or module is not initialized.
00065  */
00066 pm_peer_id_t peer_id_allocate(pm_peer_id_t peer_id);
00067 
00068 
00069 /**@brief Function for freeing a peer ID and clearing all data associated with it in persistent
00070  *        storage.
00071  *
00072  * @param[in]  peer_id  Peer ID to free.
00073  */
00074 void peer_id_free(pm_peer_id_t peer_id);
00075 
00076 
00077 /**@brief Function for finding out whether a peer ID is in use.
00078  *
00079  * @param[in]  peer_id  The peer ID to inquire about.
00080  *
00081  * @retval  true   peer_id is in use.
00082  * @retval  false  peer_id is free, or the module is not initialized.
00083  */
00084 bool peer_id_is_allocated(pm_peer_id_t peer_id);
00085 
00086 
00087 /**@brief Function for getting the next peer ID in the sequence of all used peer IDs. Can be
00088  *        used to loop through all used peer IDs.
00089  *
00090  * @note @ref PM_PEER_ID_INVALID is considered to be before the first and after the last ordinary
00091  *       peer ID.
00092  *
00093  * @param[in]  prev_peer_id  The previous peer ID.
00094  *
00095  * @return  The next peer ID.
00096  * @return  The first used peer ID  if prev_peer_id was @ref PM_PEER_ID_INVALID.
00097  * @retval  PM_PEER_ID_INVALID      if prev_peer_id was the last ordinary peer ID or the module is
00098  *                                  not initialized.
00099  */
00100 pm_peer_id_t peer_id_next_id_get(pm_peer_id_t prev_peer_id);
00101 
00102 
00103 /**@brief Function for querying the number of valid peer IDs available. I.E the number of peers
00104  *        in persistent storage.
00105  *
00106  * @return  The number of valid peer IDs, or 0 if module is not initialized.
00107  */
00108 uint32_t peer_id_n_ids(void);
00109 
00110 /** @} */
00111 
00112 #endif /* PEER_ID_H__ */