Changeset 7:e5af94b04946 in freeDiameter for include
- Timestamp:
- Sep 4, 2009, 6:05:25 PM (15 years ago)
- Branch:
- default
- Phase:
- public
- Location:
- include/freeDiameter
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
include/freeDiameter/freeDiameter.h
r1 r7 111 111 112 112 113 114 /***************************************/ 115 /* Dispatch module, daemon's part */ 116 /***************************************/ 117 118 enum { 119 DISP_APP_AUTH = 1, 120 DISP_APP_ACCT = 2 121 }; 122 /* 123 * FUNCTION: fd_disp_app_support 124 * 125 * PARAMETERS: 126 * app : The dictionary object corresponding to the Application. 127 * vendor : (Optional) the dictionary object of a Vendor to claim support in Vendor-Specific-Application-Id 128 * flags : Combination of DISP_APP_* flags. 129 * 130 * DESCRIPTION: 131 * Registers an application to be advertized in CER/CEA exchanges. 132 * Messages with an application-id matching a registered value are passed to the dispatch module, 133 * while other messages are simply relayed or an error is returned (if local node does not relay) 134 * 135 * RETURN VALUE: 136 * 0 : The application support is registered. 137 * EINVAL : A parameter is invalid. 138 */ 139 int fd_disp_app_support ( struct dict_object * app, struct dict_object * vendor, int flags ); 140 141 /* Note: if we want to support capabilities updates, we'll have to add possibility to remove an app as well... */ 142 143 113 144 #endif /* _FREEDIAMETER_H */ -
include/freeDiameter/libfreeDiameter.h
r6 r7 1508 1508 1509 1509 /*============================================================*/ 1510 /* DISPATCH */1511 /*============================================================*/1512 1513 /* Dispatch module (passing incoming messages to extensions registered callbacks)1514 * is split between the library and the daemon.1515 *1516 * The library provides the support for associating dispatch callbacks with1517 * dictionary objects.1518 *1519 * The daemon is responsible for calling the callbacks for a message when appropriate.1520 *1521 *1522 * The dispatch module has two main roles:1523 * - help determine if a message can be handled locally (during the routing step)1524 * This decision involves only the application-id of the message.1525 * - pass the message to the callback(s) that will handle it (during the dispatch step)1526 *1527 * These are the possibilities for registering a so-called dispatch callback:1528 *1529 * -> For All messages.1530 * This callback is called for all messages that are handled locally. This should be used only1531 * for debug purpose.1532 *1533 * -> by AVP value (constants only).1534 * This callback will be called when a message is received and contains an AVP with a specified enumerated value.1535 *1536 * -> by AVP.1537 * This callback will be called when the received message contains a certain AVP.1538 *1539 * -> by command-code.1540 * This callback will be called when the message is a specific command (and 'R' flag).1541 *1542 * -> by application.1543 * This callback will be called when the message has a specific application-id.1544 *1545 * ( by vendor: would this be useful? it may be added later)1546 */1547 enum disp_how {1548 DISP_HOW_ANY = 1, /* Any message. This should be only used for debug. */1549 DISP_HOW_APPID, /* Any message with the specified application-id */1550 DISP_HOW_CC, /* Messages of the specified command-code (request or answer). App id may be specified. */1551 DISP_HOW_AVP, /* Messages containing a specific AVP. Command-code and App id may be specified. */1552 DISP_HOW_AVP_ENUMVAL /* Messages containing a specific AVP with a specific enumerated value. Command-code and App id may be specified. */1553 };1554 /*1555 * Several criteria may be selected at the same time, for example command-code AND application id.1556 *1557 * If several callbacks are registered for the same object, their order is unspecified.1558 * The order in which the callbacks are called is:1559 * DISP_HOW_ANY1560 * DISP_HOW_AVP_ENUMVAL & DISP_HOW_AVP1561 * DISP_HOW_CC1562 * DISP_HOW_APPID1563 */1564 1565 /* When a callback is registered, a "when" argument is passed in addition to the disp_how value,1566 * to specify which values the criteria must match. */1567 struct disp_when {1568 struct dict_object * app_id;1569 struct dict_object * command;1570 struct dict_object * avp;1571 struct dict_object * value;1572 };1573 1574 /* Here is the details on this "when" argument, depending on the disp_how value.1575 *1576 * DISP_HOW_ANY.1577 * In this case, "when" must be NULL.1578 *1579 * DISP_HOW_APPID.1580 * Only the "app_id" field must be set, other fields are ignored. It points to a dictionary object of type DICT_APPLICATION.1581 *1582 * DISP_HOW_CC.1583 * The "command" field must be defined and point to a dictionary object of type DICT_COMMAND.1584 * The "app_id" may be also set. In the case it is set, it restricts the callback to be called only with this command-code and app id.1585 * The other fields are ignored.1586 *1587 * DISP_HOW_AVP.1588 * The "avp" field of the structure must be set and point to a dictionary object of type DICT_AVP.1589 * The "app_id" field may be set to restrict the messages matching to a specific app id.1590 * The "command" field may also be set to a valid DICT_COMMAND object.1591 * The content of the "value" field is ignored.1592 *1593 * DISP_HOW_AVP_ENUMVAL.1594 * All fields have the same constraints and meaning as in DISP_REG_AVP. In addition, the "value" field must be set1595 * and points to a valid DICT_ENUMVAL object.1596 *1597 * Here is a sumary of the fields: ( M : must be set; m : may be set; 0 : ignored )1598 * field: app_id command avp value1599 * APPID : M 0 0 01600 * CC : m M 0 01601 * AVP : m m M 01602 * ENUMVA: m m M M1603 */1604 1605 /* The callbacks that are registered have the following prototype:1606 *1607 * int dispatch_callback( struct msg ** msg, struct avp * avp, struct session * session, int * is_answer );1608 *1609 * FUNCTION: dispatch_callback1610 *1611 * PARAMETERS:1612 * msg : the received message on function entry. may be updated to answer on return (see description)1613 * avp : for callbacks registered with DISP_HOW_AVP or DISP_HOW_AVP_ENUMVAL, direct link to the triggering AVP.1614 * session : if the message contains a Session-Id AVP, the corresponding session object.1615 *1616 * DESCRIPTION:1617 * Create a new AVP instance.1618 *1619 * RETURN VALUE:1620 * 0 : The AVP is created.1621 * EINVAL : A parameter is invalid.1622 * (other standard errors may be returned, too, with their standard meaning. Example:1623 * ENOMEM : Memory allocation for the new avp failed.)1624 */1625 1626 1627 /*============================================================*/1628 1510 /* MESSAGES */ 1629 1511 /*============================================================*/ … … 2196 2078 2197 2079 2080 /*============================================================*/ 2081 /* DISPATCH */ 2082 /*============================================================*/ 2083 2084 /* Dispatch module (passing incoming messages to extensions registered callbacks) 2085 * is split between the library and the daemon. 2086 * 2087 * The library provides the support for associating dispatch callbacks with 2088 * dictionary objects. 2089 * 2090 * The daemon is responsible for calling the callbacks for a message when appropriate. 2091 * 2092 * 2093 * The dispatch module has two main roles: 2094 * - help determine if a message can be handled locally (during the routing step) 2095 * This decision involves only the application-id of the message. 2096 * - pass the message to the callback(s) that will handle it (during the dispatch step) 2097 * 2098 * The first role is handled by the daemon. 2099 * 2100 * About the second, these are the possibilities for registering a dispatch callback: 2101 * 2102 * -> For All messages. 2103 * This callback is called for all messages that are handled locally. This should be used only 2104 * for debug purpose. 2105 * 2106 * -> by AVP value (constants only). 2107 * This callback will be called when a message is received and contains an AVP with a specified enumerated value. 2108 * 2109 * -> by AVP. 2110 * This callback will be called when the received message contains a certain AVP. 2111 * 2112 * -> by command-code. 2113 * This callback will be called when the message is a specific command (and 'R' flag). 2114 * 2115 * -> by application. 2116 * This callback will be called when the message has a specific application-id. 2117 * 2118 * ( by vendor: would this be useful? it may be added later) 2119 */ 2120 enum disp_how { 2121 DISP_HOW_ANY = 1, /* Any message. This should be only used for debug. */ 2122 DISP_HOW_APPID, /* Any message with the specified application-id */ 2123 DISP_HOW_CC, /* Messages of the specified command-code (request or answer). App id may be specified. */ 2124 DISP_HOW_AVP, /* Messages containing a specific AVP. Command-code and App id may be specified. */ 2125 DISP_HOW_AVP_ENUMVAL /* Messages containing a specific AVP with a specific enumerated value. Command-code and App id may be specified. */ 2126 }; 2127 /* 2128 * Several criteria may be selected at the same time, for example command-code AND application id. 2129 * 2130 * If several callbacks are registered for the same object, they are called in the order they were registered. 2131 * The order in which the callbacks are called is: 2132 * DISP_HOW_ANY 2133 * DISP_HOW_AVP_ENUMVAL & DISP_HOW_AVP 2134 * DISP_HOW_CC 2135 * DISP_HOW_APPID 2136 */ 2137 2138 /* When a callback is registered, a "when" argument is passed in addition to the disp_how value, 2139 * to specify which values the criteria must match. */ 2140 struct disp_when { 2141 struct dict_object * app; 2142 struct dict_object * command; 2143 struct dict_object * avp; 2144 struct dict_object * value; 2145 }; 2146 2147 /* Note that all the dictionary objects should really belong to the same dictionary! 2148 * 2149 * Here is the details on this "when" argument, depending on the disp_how value. 2150 * 2151 * DISP_HOW_ANY. 2152 * In this case, "when" must be NULL. 2153 * 2154 * DISP_HOW_APPID. 2155 * Only the "app_id" field must be set, other fields are ignored. It points to a dictionary object of type DICT_APPLICATION. 2156 * 2157 * DISP_HOW_CC. 2158 * The "command" field must be defined and point to a dictionary object of type DICT_COMMAND. 2159 * The "app_id" may be also set. In the case it is set, it restricts the callback to be called only with this command-code and app id. 2160 * The other fields are ignored. 2161 * 2162 * DISP_HOW_AVP. 2163 * The "avp" field of the structure must be set and point to a dictionary object of type DICT_AVP. 2164 * The "app_id" field may be set to restrict the messages matching to a specific app id. 2165 * The "command" field may also be set to a valid DICT_COMMAND object. 2166 * The content of the "value" field is ignored. 2167 * 2168 * DISP_HOW_AVP_ENUMVAL. 2169 * All fields have the same constraints and meaning as in DISP_REG_AVP. In addition, the "value" field must be set 2170 * and points to a valid DICT_ENUMVAL object. 2171 * 2172 * Here is a sumary of the fields: ( M : must be set; m : may be set; 0 : ignored ) 2173 * field: app_id command avp value 2174 * APPID : M 0 0 0 2175 * CC : m M 0 0 2176 * AVP : m m M 0 2177 * ENUMVA: m m M M 2178 */ 2179 2180 enum disp_action { 2181 DISP_ACT_CONT, /* The next handler should be called, unless *msg == NULL. */ 2182 DISP_ACT_SEND /* The updated message must be sent. No further callback is called. */ 2183 }; 2184 /* The callbacks that are registered have the following prototype: 2185 * int dispatch_callback( struct msg ** msg, struct avp * avp, struct session * session, enum disp_action * action ); 2186 * 2187 * CALLBACK: dispatch_callback 2188 * 2189 * PARAMETERS: 2190 * msg : the received message on function entry. may be updated to answer on return (see description) 2191 * avp : for callbacks registered with DISP_HOW_AVP or DISP_HOW_AVP_ENUMVAL, direct link to the triggering AVP. 2192 * session : if the message contains a Session-Id AVP, the corresponding session object, NULL otherwise. 2193 * action : upon return, this tells the daemon what to do next. 2194 * 2195 * DESCRIPTION: 2196 * Called when a received message matchs the condition for which the callback was registered. 2197 * This callback may do any kind of processing on the message, including: 2198 * - create an answer for a request. 2199 * - proxy a request or message, add / remove the Proxy-Info AVP, then forward the message. 2200 * - update a routing table or start a connection with a new peer, then forward the message. 2201 * - ... 2202 * 2203 * When *action == DISP_ACT_SEND on callback return, the msg pointed by *msg is passed to the routing module for sending. 2204 * When *action == DISP_ACT_CONT, the next registered callback is called. 2205 * When the last callback gives also DISP_ACT_CONT action value, a default handler is called. It's behavior is as follow: 2206 * - if the message is an answer, it is discarded. 2207 * - if the message is a request, it is passed again to the routing stack, and marked as non-local handling. 2208 * 2209 * RETURN VALUE: 2210 * 0 : The callback executed successfully and updated *action appropriately. 2211 * !0 : standard errors. In case of error, the message is discarded. 2212 */ 2213 2214 /* This structure represents a handler for a registered callback, allowing its de-registration */ 2215 struct disp_hdl; 2216 2217 /* 2218 * FUNCTION: fd_disp_register 2219 * 2220 * PARAMETERS: 2221 * cb : The callback function to register (see dispatch_callback description above). 2222 * how : How the callback must be registered. 2223 * when : Values that must match, depending on the how argument. 2224 * handle : On success, a handler to the registered callback is stored here if not NULL. 2225 * This handler can be used to unregister the cb. 2226 * 2227 * DESCRIPTION: 2228 * Register a new callback to handle messages delivered locally. 2229 * 2230 * RETURN VALUE: 2231 * 0 : The callback is registered. 2232 * EINVAL : A parameter is invalid. 2233 * ENOMEM : Not enough memory to complete the operation 2234 */ 2235 int fd_disp_register ( int (*cb)( struct msg **, struct avp *, struct session *, enum disp_action *), 2236 enum disp_how how, struct disp_when * when, struct disp_hdl ** handle ); 2237 2238 /* 2239 * FUNCTION: fd_disp_unregister 2240 * 2241 * PARAMETERS: 2242 * handle : Location of the handle of the callback that must be unregistered. 2243 * 2244 * DESCRIPTION: 2245 * Removes a callback previously registered by fd_disp_register. 2246 * 2247 * RETURN VALUE: 2248 * 0 : The callback is unregistered. 2249 * EINVAL : A parameter is invalid. 2250 */ 2251 int fd_disp_unregister ( struct disp_hdl ** handle ); 2252 2253 /* 2254 * FUNCTION: fd_msg_dispatch 2255 * 2256 * PARAMETERS: 2257 * msg : A msg object that have already been fd_msg_parse_dict. 2258 * session : The session corresponding to this object, if any. 2259 * action : Upon return, the action that must be taken on the message 2260 * 2261 * DESCRIPTION: 2262 * Call all handlers registered for a given message. 2263 * The session must have already been resolved on entry. 2264 * The msg pointed may be updated during this process. 2265 * Upon return, the action parameter points to what must be done next. 2266 * 2267 * RETURN VALUE: 2268 * 0 : Success. 2269 * EINVAL : A parameter is invalid. 2270 * (other errors) 2271 */ 2272 int fd_msg_dispatch ( struct msg ** msg, struct session * session, enum disp_action *action ); 2273 2274 2198 2275 2199 2276 /*============================================================*/
Note: See TracChangeset
for help on using the changeset viewer.