Annotation of embedaddon/bird2/nest/proto-hooks.c, revision 1.1.1.1

1.1       misho       1: /*
                      2:  *     BIRD -- Documentation for Protocol Hooks (dummy source file)
                      3:  *
                      4:  *     (c) 2000 Martin Mares <mj@ucw.cz>
                      5:  *
                      6:  *     Can be freely distributed and used under the terms of the GNU GPL.
                      7:  */
                      8: 
                      9: /**
                     10:  * DOC: Protocol hooks
                     11:  *
                     12:  * Each protocol can provide a rich set of hook functions referred to by pointers
                     13:  * in either the &proto or &protocol structure. They are called by the core whenever
                     14:  * it wants the protocol to perform some action or to notify the protocol about
                     15:  * any change of its environment. All of the hooks can be set to %NULL which means
                     16:  * to ignore the change or to take a default action.
                     17:  */
                     18: 
                     19: /**
                     20:  * preconfig - protocol preconfiguration
                     21:  * @p: a routing protocol
                     22:  * @c: new configuration
                     23:  *
                     24:  * The preconfig() hook is called before parsing of a new configuration.
                     25:  */
                     26: void preconfig(struct protocol *p, struct config *c)
                     27: { DUMMY; }
                     28: 
                     29: /**
                     30:  * postconfig - instance post-configuration
                     31:  * @c: instance configuration
                     32:  *
                     33:  * The postconfig() hook is called for each configured instance after
                     34:  * parsing of the new configuration is finished.
                     35:  */
                     36: void postconfig(struct proto_config *c)
                     37: { DUMMY; }
                     38: 
                     39: /**
                     40:  * init - initialize an instance
                     41:  * @c: instance configuration
                     42:  *
                     43:  * The init() hook is called by the core to create a protocol instance
                     44:  * according to supplied protocol configuration.
                     45:  *
                     46:  * Result: a pointer to the instance created
                     47:  */
                     48: struct proto *init(struct proto_config *c)
                     49: { DUMMY; }
                     50: 
                     51: /**
                     52:  * reconfigure - request instance reconfiguration
                     53:  * @p: an instance
                     54:  * @c: new configuration
                     55:  *
                     56:  * The core calls the reconfigure() hook whenever it wants to ask the
                     57:  * protocol for switching to a new configuration. If the reconfiguration
                     58:  * is possible, the hook returns 1. Otherwise, it returns 0 and the core
                     59:  * will shut down the instance and start a new one with the new configuration.
                     60:  *
                     61:  * After the protocol confirms reconfiguration, it must no longer keep any
                     62:  * references to the old configuration since the memory it's stored in can
                     63:  * be re-used at any time.
                     64:  */
                     65: int reconfigure(struct proto *p, struct proto_config *c)
                     66: { DUMMY; }
                     67: 
                     68: /**
                     69:  * dump - dump protocol state
                     70:  * @p: an instance
                     71:  *
                     72:  * This hook dumps the complete state of the instance to the
                     73:  * debug output.
                     74:  */
                     75: void dump(struct proto *p)
                     76: { DUMMY; }
                     77: 
                     78: /**
                     79:  * dump_attrs - dump protocol-dependent attributes
                     80:  * @e: a route entry
                     81:  *
                     82:  * This hook dumps all attributes in the &rte which belong to this
                     83:  * protocol to the debug output.
                     84:  */
                     85: void dump_attrs(rte *e)
                     86: { DUMMY; }
                     87: 
                     88: /**
                     89:  * start - request instance startup
                     90:  * @p: protocol instance
                     91:  *
                     92:  * The start() hook is called by the core when it wishes to start
                     93:  * the instance. Multitable protocols should lock their tables here.
                     94:  *
                     95:  * Result: new protocol state
                     96:  */
                     97: int start(struct proto *p)
                     98: { DUMMY; }
                     99: 
                    100: /**
                    101:  * shutdown - request instance shutdown
                    102:  * @p: protocol instance
                    103:  *
                    104:  * The stop() hook is called by the core when it wishes to shut
                    105:  * the instance down for some reason.
                    106:  *
                    107:  * Returns: new protocol state
                    108:  */
                    109: int shutdown(struct proto *p)
                    110: { DUMMY; }
                    111: 
                    112: /**
                    113:  * cleanup - request instance cleanup
                    114:  * @p: protocol instance
                    115:  *
                    116:  * The cleanup() hook is called by the core when the protocol became
                    117:  * hungry/down, i.e. all protocol ahooks and routes are flushed.
                    118:  * Multitable protocols should unlock their tables here.
                    119:  */
                    120: void cleanup(struct proto *p)
                    121: { DUMMY; }
                    122: 
                    123: /**
                    124:  * get_status - get instance status
                    125:  * @p: protocol instance
                    126:  * @buf: buffer to be filled with the status string
                    127:  *
                    128:  * This hook is called by the core if it wishes to obtain an brief one-line user friendly
                    129:  * representation of the status of the instance to be printed by the <cf/show protocols/
                    130:  * command.
                    131:  */
                    132: void get_status(struct proto *p, byte *buf)
                    133: { DUMMY; }
                    134: 
                    135: /**
                    136:  * get_route_info - get route information
                    137:  * @e: a route entry
                    138:  * @buf: buffer to be filled with the resulting string
                    139:  * @attrs: extended attributes of the route
                    140:  *
                    141:  * This hook is called to fill the buffer @buf with a brief user friendly
                    142:  * representation of metrics of a route belonging to this protocol.
                    143:  */
                    144: void get_route_info(rte *e, byte *buf, ea_list *attrs)
                    145: { DUMMY; }
                    146: 
                    147: /**
                    148:  * get_attr - get attribute information
                    149:  * @a: an extended attribute
                    150:  * @buf: buffer to be filled with attribute information
                    151:  * @buflen: a length of the @buf parameter
                    152:  *
                    153:  * The get_attr() hook is called by the core to obtain a user friendly
                    154:  * representation of an extended route attribute. It can either leave
                    155:  * the whole conversion to the core (by returning %GA_UNKNOWN), fill
                    156:  * in only attribute name (and let the core format the attribute value
                    157:  * automatically according to the type field; by returning %GA_NAME)
                    158:  * or doing the whole conversion (used in case the value requires extra
                    159:  * care; return %GA_FULL).
                    160:  */
                    161: int get_attr(eattr *a, byte *buf, int buflen)
                    162: { DUMMY; }
                    163: 
                    164: /**
                    165:  * if_notify - notify instance about interface changes
                    166:  * @p: protocol instance
                    167:  * @flags: interface change flags
                    168:  * @i: the interface in question
                    169:  *
                    170:  * This hook is called whenever any network interface changes its status.
                    171:  * The change is described by a combination of status bits (%IF_CHANGE_xxx)
                    172:  * in the @flags parameter.
                    173:  */
                    174: void if_notify(struct proto *p, unsigned flags, struct iface *i)
                    175: { DUMMY; }
                    176: 
                    177: /**
                    178:  * ifa_notify - notify instance about interface address changes
                    179:  * @p: protocol instance
                    180:  * @flags: address change flags
                    181:  * @a: the interface address
                    182:  *
                    183:  * This hook is called to notify the protocol instance about an interface
                    184:  * acquiring or losing one of its addresses. The change is described by
                    185:  * a combination of status bits (%IF_CHANGE_xxx) in the @flags parameter.
                    186:  */
                    187: void ifa_notify(struct proto *p, unsigned flags, struct ifa *a)
                    188: { DUMMY; }
                    189: 
                    190: /**
                    191:  * rt_notify - notify instance about routing table change
                    192:  * @p: protocol instance
                    193:  * @channel: notifying channel
                    194:  * @net: a network entry
                    195:  * @new: new route for the network
                    196:  * @old: old route for the network
                    197:  * @attrs: extended attributes associated with the @new entry
                    198:  *
                    199:  * The rt_notify() hook is called to inform the protocol instance about
                    200:  * changes in the connected routing table @table, that is a route @old
                    201:  * belonging to network @net being replaced by a new route @new with
                    202:  * extended attributes @attrs. Either @new or @old or both can be %NULL
                    203:  * if the corresponding route doesn't exist.
                    204:  *
                    205:  * If the type of route announcement is RA_OPTIMAL, it is an
                    206:  * announcement of optimal route change, @new stores the new optimal
                    207:  * route and @old stores the old optimal route.
                    208:  *
                    209:  * If the type of route announcement is RA_ANY, it is an announcement
                    210:  * of any route change, @new stores the new route and @old stores the
                    211:  * old route from the same protocol.
                    212:  *
                    213:  * @p->accept_ra_types specifies which kind of route announcements
                    214:  * protocol wants to receive.
                    215:  */
                    216: void rt_notify(struct proto *p, net *net, rte *new, rte *old, ea_list *attrs)
                    217: { DUMMY; }
                    218: 
                    219: /**
                    220:  * neigh_notify - notify instance about neighbor status change
                    221:  * @neigh: a neighbor cache entry
                    222:  *
                    223:  * The neigh_notify() hook is called by the neighbor cache whenever
                    224:  * a neighbor changes its state, that is it gets disconnected or a
                    225:  * sticky neighbor gets connected.
                    226:  */
                    227: void neigh_notify(neighbor *neigh)
                    228: { DUMMY; }
                    229: 
                    230: /**
                    231:  * make_tmp_attrs - convert embedded attributes to temporary ones
                    232:  * @e: route entry
                    233:  * @pool: linear pool to allocate attribute memory in
                    234:  *
                    235:  * This hook is called by the routing table functions if they need
                    236:  * to convert the protocol attributes embedded directly in the &rte
                    237:  * to temporary extended attributes in order to distribute them
                    238:  * to other protocols or to filters. make_tmp_attrs() creates
                    239:  * an &ea_list in the linear pool @pool, fills it with values of the
                    240:  * temporary attributes and returns a pointer to it.
                    241:  */
                    242: ea_list *make_tmp_attrs(rte *e, struct linpool *pool)
                    243: { DUMMY; }
                    244: 
                    245: /**
                    246:  * store_tmp_attrs - convert temporary attributes to embedded ones
                    247:  * @e: route entry
                    248:  * @attrs: temporary attributes to be converted
                    249:  *
                    250:  * This hook is an exact opposite of make_tmp_attrs() -- it takes
                    251:  * a list of extended attributes and converts them to attributes
                    252:  * embedded in the &rte corresponding to this protocol.
                    253:  *
                    254:  * You must be prepared for any of the attributes being missing
                    255:  * from the list and use default values instead.
                    256:  */
                    257: void store_tmp_attrs(rte *e, ea_list *attrs)
                    258: { DUMMY; }
                    259: 
                    260: /**
                    261:  * preexport - pre-filtering decisions before route export
                    262:  * @p: protocol instance the route is going to be exported to
                    263:  * @e: the route in question
                    264:  * @attrs: extended attributes of the route
                    265:  * @pool: linear pool for allocation of all temporary data
                    266:  *
                    267:  * The preexport() hook is called as the first step of a exporting
                    268:  * a route from a routing table to the protocol instance. It can modify
                    269:  * route attributes and force acceptance or rejection of the route before
                    270:  * the user-specified filters are run. See rte_announce() for a complete description
                    271:  * of the route distribution process.
                    272:  *
                    273:  * The standard use of this hook is to reject routes having originated
                    274:  * from the same instance and to set default values of the protocol's metrics.
                    275:  *
                    276:  * Result: 1 if the route has to be accepted, -1 if rejected and 0 if it
                    277:  * should be passed to the filters.
                    278:  */
                    279: int preexport(struct proto *p, rte **e, ea_list **attrs, struct linpool *pool)
                    280: { DUMMY; }
                    281: 
                    282: /**
                    283:  * rte_recalculate - prepare routes for comparison
                    284:  * @table: a routing table
                    285:  * @net: a network entry
                    286:  * @new: new route for the network
                    287:  * @old: old route for the network
                    288:  * @old_best: old best route for the network (may be NULL)
                    289:  *
                    290:  * This hook is called when a route change (from @old to @new for a
                    291:  * @net entry) is propagated to a @table. It may be used to prepare
                    292:  * routes for comparison by rte_better() in the best route
                    293:  * selection. @new may or may not be in @net->routes list,
                    294:  * @old is not there.
                    295:  *
                    296:  * Result: 1 if the ordering implied by rte_better() changes enough
                    297:  * that full best route calculation have to be done, 0 otherwise.
                    298:  */
                    299: int rte_recalculate(struct rtable *table, struct network *net, struct rte *new, struct rte *old, struct rte *old_best)
                    300: { DUMMY; }
                    301: 
                    302: /**
                    303:  * rte_better - compare metrics of two routes
                    304:  * @new: the new route
                    305:  * @old: the original route
                    306:  *
                    307:  * This hook gets called when the routing table contains two routes
                    308:  * for the same network which have originated from different instances
                    309:  * of a single protocol and it wants to select which one is preferred
                    310:  * over the other one. Protocols usually decide according to route metrics.
                    311:  *
                    312:  * Result: 1 if @new is better (more preferred) than @old, 0 otherwise.
                    313:  */
                    314: int rte_better(rte *new, rte *old)
                    315: { DUMMY; }
                    316: 
                    317: /**
                    318:  * rte_same - compare two routes
                    319:  * @e1: route
                    320:  * @e2: route
                    321:  *
                    322:  * The rte_same() hook tests whether the routes @e1 and @e2 belonging
                    323:  * to the same protocol instance have identical contents. Contents of
                    324:  * &rta, all the extended attributes and &rte preference are checked
                    325:  * by the core code, no need to take care of them here.
                    326:  *
                    327:  * Result: 1 if @e1 is identical to @e2, 0 otherwise.
                    328:  */
                    329: int rte_same(rte *e1, rte *e2)
                    330: { DUMMY; }
                    331: 
                    332: /**
                    333:  * rte_insert - notify instance about route insertion
                    334:  * @n: network
                    335:  * @e: route
                    336:  *
                    337:  * This hook is called whenever a &rte belonging to the instance
                    338:  * is accepted for insertion to a routing table.
                    339:  *
                    340:  * Please avoid using this function in new protocols.
                    341:  */
                    342: void rte_insert(net *n, rte *e)
                    343: { DUMMY; }
                    344: 
                    345: /**
                    346:  * rte_remove - notify instance about route removal
                    347:  * @n: network
                    348:  * @e: route
                    349:  *
                    350:  * This hook is called whenever a &rte belonging to the instance
                    351:  * is removed from a routing table.
                    352:  *
                    353:  * Please avoid using this function in new protocols.
                    354:  */
                    355: void rte_remove(net *n, rte *e)
                    356: { DUMMY; }

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>