Annotation of embedaddon/bird/nest/proto-hooks.c, revision 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: * @table: a routing table
! 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: * import_control - pre-filtering decisions on route import
! 262: * @p: protocol instance the route is going to be imported 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 import_control() 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 regardless
! 270: * of user-specified filters. 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 import_control(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>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to proto-hooks.c CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / nest