Interface: moteiv.tos.lib.sp.SPNeighbor

interface SPNeighbor

Manage entries in the SP neighbor table.

Author:
Joe Polastre, Moteiv Corporation <info@moteiv.com>

Commands
command void change(sp_neighbor_t *neighbor) Notify SP that the contents of a neighbor table entry have changed.
command result_t find() Try to find more neighbors.
command result_t findDone() Stop finding new neighbors.
command uint8_t first()
command sp_neighbor_t *get(uint8_t n) Get the neighbor at position i.
command sp_neighbor_flags_t getFlags(sp_neighbor_t *neighbor) Get the flags associated with this entry.
command result_t insert(sp_neighbor_t *neighbor) Insert a new neighbor to the table.
command uint8_t max() Get the maximum number of entries in the table.
command uint8_t next(uint8_t n)
command uint8_t populated()
command result_t remove(sp_neighbor_t *neighbor) Remove a neighbor from the neighbor table.
command bool valid(uint8_t n)

Events
event result_t admit(sp_neighbor_t *neighbor) Query from SP to user services asking if the specified neighbor should be admitted to the SP Neighbor Table.
event void evicted(sp_neighbor_t *neighbor) The neighbor was evicted by another process/task.
event void expired(sp_neighbor_t *neighbor) Notification that a neighbor's schedule has expired.
event void update(sp_neighbor_t *neighbor) Notification than an entry has been updated ("changed").

Commands - Details

change

command void change(sp_neighbor_t *neighbor)

Notify SP that the contents of a neighbor table entry have changed. Any service can change the contents of a neighbor table entry. All other SPNeighbor services are notified of the change through the update() event.

WARNING: Do not modify/change a neighbor entry when the neighbor is currently active. Always check the SP_FLAG_LINK_ACTIVE flag before performing any modifications. If the link is active, wait until the expiration event before performing schedule modifications. Failure to heed this warning may result in unpredictable operation.


find

command result_t find()

Try to find more neighbors. All find commands must have a corresponding findDone command following it. find commands are reference counted, so make sure that nested finds also have the appropriate un-nesting of findDone commands.

findDone

command result_t findDone()

Stop finding new neighbors.

first

command uint8_t first()

get

command sp_neighbor_t *get(uint8_t n)

Get the neighbor at position i.

getFlags

command sp_neighbor_flags_t getFlags(sp_neighbor_t *neighbor)

Get the flags associated with this entry. Flags are READ-ONLY.

Flags are:

  SP_FLAG_TABLE   -- the entry is in the neighbor table
  SP_FLAG_BUSY    -- the entry is currently busy
  SP_FLAG_LISTEN  -- the listen bit is set
  SP_FLAG_LINK_ACTIVE -- the link is currently on/active
 

insert

command result_t insert(sp_neighbor_t *neighbor)

Insert a new neighbor to the table. If the neighbor is already in the table, its values are refreshed and the 'update' event is signalled to all other services.

max

command uint8_t max()

Get the maximum number of entries in the table.

next

command uint8_t next(uint8_t n)

populated

command uint8_t populated()

remove

command result_t remove(sp_neighbor_t *neighbor)

Remove a neighbor from the neighbor table. You can only remove a neighbor if you put it into the neighbor table (if you are the owner).

valid

command bool valid(uint8_t n)

Events - Details

admit

event result_t admit(sp_neighbor_t *neighbor)

Query from SP to user services asking if the specified neighbor should be admitted to the SP Neighbor Table.

Returns:
SUCCESS to admit the neighbor to the neighbor table.

evicted

event void evicted(sp_neighbor_t *neighbor)

The neighbor was evicted by another process/task.

expired

event void expired(sp_neighbor_t *neighbor)

Notification that a neighbor's schedule has expired. Only the service that owns the neighbor is notified. If multiple schedules are desired, multiple sp_neighbor_t entries should be inserted into the table. By only notifying the service that set the schedule, SP is providing a minimal amount of protection. SP takes care of computing the union of all schedules for a particular neighbor.

Update the schedule and then call the 'change()' command to notify SP of the updated schedule.


update

event void update(sp_neighbor_t *neighbor)

Notification than an entry has been updated ("changed").