Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Announcements

The Announcement primitive does local area announcements.

An announcement is an (ID, value) tuple that is disseminated to local area neighbors. An application or protocol can explicitly listen to announcements from neighbors. When an announcement is heard, a callback is invoked.

Announcements can be used for a variety of network mechanisms such as neighbor discovery, node-level service discovery, or routing metric dissemination.

Application programs and protocols register announcements with the announcement module. An announcement back-end, implemented by the system, takes care of sending out announcements over the radio, as well as collecting announcements heard from neighbors.

Data Structures

struct  announcement
 Representation of an announcement. More...
 

Files

file  announcement.h
 
    Header file for the announcement primitive

 

Typedefs

typedef void(* announcement_callback_t )(struct announcement *a, const linkaddr_t *from, uint16_t id, uint16_t val)
 

Application API

void announcement_register (struct announcement *a, uint16_t id, announcement_callback_t callback)
 Register an announcement. More...
 
void announcement_remove (struct announcement *a)
 Remove a previously registered announcement. More...
 
void announcement_set_value (struct announcement *a, uint16_t value)
 Set the value of an announcement. More...
 
void announcement_remove_value (struct announcement *a)
 Remove the value of an announcement. More...
 
void announcement_bump (struct announcement *a)
 Bump an announcement. More...
 
void announcement_listen (int periods)
 Listen for announcements for a specific amount of announcement periods. More...
 

System API

enum  {
  ANNOUNCEMENT_NOBUMP,
  ANNOUNCEMENT_BUMP
}
 
typedef void(* announcement_observer )(uint16_t id, uint8_t has_value, uint16_t newvalue, uint16_t oldvalue, uint8_t bump)
 
void announcement_init (void)
 Initialize the announcement module. More...
 
struct announcementannouncement_list (void)
 Get the list of registered announcements. More...
 
void announcement_heard (const linkaddr_t *from, uint16_t id, uint16_t value)
 Inform the announcement module of an incoming announcement. More...
 
void announcement_register_listen_callback (void(*callback)(int time))
 Register a listen callback with the announcement module. More...
 
void announcement_register_observer_callback (announcement_observer observer)
 Register an observer callback with the announcement module. More...
 

typedef void(* announcement_callback_t)(struct announcement *a, const linkaddr_t *from, uint16_t id, uint16_t val)
typedef void(* announcement_observer)(uint16_t id, uint8_t has_value, uint16_t newvalue, uint16_t oldvalue, uint8_t bump)

anonymous enum
Enumerator
ANNOUNCEMENT_NOBUMP 
ANNOUNCEMENT_BUMP 

void announcement_bump ( struct announcement a)

Bump an announcement.

Parameters
aA pointer to a struct announcement that has previously been registered

This function is called to inform the announcement module that a particular announcement has changed in a way that it should be bumped. When an announcement is bumped, the announcement back-end may send out a new announcement to neighbors.

void announcement_heard ( const linkaddr_t from,
uint16_t  id,
uint16_t  value 
)

Inform the announcement module of an incoming announcement.

Parameters
fromThe address of the sender of the announcement
idThe identifier of the announcement
valueThe value of the announcement
        This function is called by the back-end to inform the
        announcement module that an announcement from a
        neighbor has been heard.
void announcement_init ( void  )

Initialize the announcement module.

This function initializes the announcement module, and is called by the system at boot up.

struct announcement* announcement_list ( void  )

Get the list of registered announcements.

Returns
The list of registered announcements
        This function returns the list of registered
        announcements. This function is used by the back-end to
        compile announcement packets from the registered
        announcements.

        The announcement list is an ordinary Contiki list, as
        defined by the \ref list "list module".
void announcement_listen ( int  periods)

Listen for announcements for a specific amount of announcement periods.

Parameters
periodsThe number of periods to listen for announcement
        This function starts to listen for announcements for
        the specified amount of announcement periods. This
        function is called to ensure that the announcement
        module hears announcements from neighbors. The
        announcement module may hear announcements even if
        listening is not explicitly enabled, but with listening
        enabled, more announcements will be heard.
void announcement_register ( struct announcement a,
uint16_t  id,
announcement_callback_t  callback 
)

Register an announcement.

Parameters
aA pointer to a struct announcement
idThe identifying number of the announcement
callbackA pointer to a callback function that is called when an announcement is heard

This function registers an announcement with the announcement module. The state of the announcement is held in a struct announcement variable, which is passed as an argument to this function. This variable must be allocated by the caller. An announcement is identified with a 16-bit number, which is passed as a parameter to the function. The announcement also has an initial value, that can later be changed with announcement_set_value().

void announcement_register_listen_callback ( void(*)(int time)  callback)

Register a listen callback with the announcement module.

Parameters
callbackA pointer to a callback function
        This function is called by the back-end to register a
        listen callback with the announcement module. The
        listen callback function is called by the announcement
        module as part of the announcement_listen() function.
void announcement_register_observer_callback ( announcement_observer  observer)

Register an observer callback with the announcement module.

Parameters
observerA pointer to an observer function
        This function is callback by the back-end to register
        an observer callback with the announcement module. The
        observer callback is called by the announcement module
        when an announcement is registered, removed, or have
        its identifier or value updated.

        The back-end may chose to send out a new announcement
        message with the updated values.
void announcement_remove ( struct announcement a)

Remove a previously registered announcement.

Parameters
aA pointer to a struct announcement that has previously been registered

This function removes an announcement that has previously been registered with announcement_register().

void announcement_remove_value ( struct announcement a)

Remove the value of an announcement.

Parameters
aA pointer to a struct announcement that has previously been registered

This function removes the value of an announcement that has previously been registered with announcement_register().

void announcement_set_value ( struct announcement a,
uint16_t  value 
)

Set the value of an announcement.

Parameters
aA pointer to a struct announcement that has previously been registered

This function sets the value of an announcement that has previously been registered with announcement_register().