Changeset 1069:544fa1be79a9 in freeDiameter for include/freeDiameter/libfdcore.h
- Timestamp:
- Apr 30, 2013, 1:09:32 PM (11 years ago)
- Branch:
- default
- Children:
- 1070:ac5c105cbc08, 1078:74bba7975864
- Phase:
- public
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
include/freeDiameter/libfdcore.h
r1067 r1069 874 874 * peer : If relevant, the pointer to the peer associated with the call. NULL otherwise. 875 875 * other : For some callbacks, the remaining information is passed in this parameter. See each hook detail. 876 * permsgdata : Structure associated with a given message, across several hooks. 877 * Same structure is associated with requests and corresponding answers. 878 * See fd_hook_data_hdl below for details. 879 * If no fd_hook_data_hdl is registered with this callback, this parameter is always NULL 876 880 * regdata : Data pointer stored at registration, opaque for the framework. 877 881 * … … 883 887 * - ... 884 888 * 885 * IMPORTANT: the callback MUST NOT change the m omory pointed by the different parameters (peer, message, ...)889 * IMPORTANT: the callback MUST NOT change the memory pointed by the different parameters (peer, message, ...) 886 890 * 887 891 * RETURN VALUE: … … 892 896 enum fd_hook_type { 893 897 894 HOOK_MESSAGE_RECEIVED = 1, 895 /* Hook called when a message has been received and the structure has been parsed successfully (list of AVPs). 896 - *msg points to the parsed message. At this time, the objects have not been dictionary resolved. If you 897 try to call fd_msg_parse_dict, it might slow down the operation of a relay agent. 898 - *peer is set if the message is received from a peer's connection, and NULL if the message is from a new client 899 connected and not yet identified 900 - *other is NULL. 901 */ 902 903 /* HOOK_DATA_RECEIVED, <-- this one is tricky to implement, will skip in the first version */ 904 /* Hook called as soon as data is received from a socket. 905 - *msg is NULL. 906 - *peer is set if the data is received from a peer's connection, and NULL if the message is from a new client 907 connected and not yet identified 908 - *other points to a structure: { . 898 HOOK_DATA_RECEIVED = 0, 899 /* Hook called as soon as a message has been received from the network, after TLS & boundary processing. 900 - {msg} is NULL. 901 - {peer} is NULL. 902 - {*other} is NULL, {other} points to a valid location where you can store a pointer. 903 This same pointer will then passed to the next hook, once message is processed. 904 IMPORTANT: free() will be called on this pointer if any problem, so this pointer must be malloc'd. 905 - {permsgdata} is NULL. 909 906 */ 910 907 908 HOOK_MESSAGE_RECEIVED, 909 /* Hook called when a message has been received and the structure has been parsed successfully (list of AVPs). 910 - {msg} points to the parsed message. At this time, the objects have not been dictionary resolved. If you 911 try to call fd_msg_parse_dict, it will slow down the operation of a relay agent. 912 - {peer} is set if the message is received from a peer's connection, and NULL if the message is from a new client 913 connected and not yet identified 914 - {*other} contains the pointer stored with the HOOK_DATA_RECEIVED hook if any, NULL otherwise. After this hook returns, free(*other) is called if not NULL. 915 - {permsgdata} points to either a new empty structure allocated for this request (cf. fd_hook_data_hdl), or the request's existing structure if the message is an answer. 916 */ 917 918 HOOK_MESSAGE_LOCAL, 919 /* Hook called when a request message has been created locally and is being sent. 920 - {msg} points to the message. 921 - {peer} is NULL 922 - {other} is NULL 923 - {permsgdata} points to a new empty structure allocated for this request (cf. fd_hook_data_hdl) 924 */ 925 911 926 HOOK_MESSAGE_SENT, 912 927 /* Hook called when a message has been sent to a peer. The message might be freed as soon as the hook function returns, 913 928 so it is not safe to store the pointer for asynchronous processing. 914 - *msgpoints to the sent message. Again, the objects may not have been dictionary resolved. If you915 try to call fd_msg_parse_dict, it mightslow down the operation of a relay agent.916 - *peeris set if the message is sent to a peer's connection, and NULL if the message is sent to a new client929 - {msg} points to the sent message. Again, the objects may not have been dictionary resolved. If you 930 try to call fd_msg_parse_dict, it will slow down the operation of a relay agent. 931 - {peer} is set if the message is sent to a peer's connection, and NULL if the message is sent to a new client 917 932 connected and not yet identified / being rejected 918 - *other is NULL. 933 - {other} is NULL. 934 - {permsgdata} points to existing structure if any, or a new structure otherwise. 935 If the message is an answer, the structure is shared with the corresponding request. 936 */ 937 938 HOOK_MESSAGE_FAILOVER, 939 /* Hook called when a message that was sent to a peer is being requeued, because e.g. the connection was teared down. 940 In that case the message will go again through the routing process. 941 - {msg} points to the corresponding request message (the answer is discarded). Again, the objects may not have been dictionary resolved. If you 942 try to call fd_msg_parse_dict, it might slow down the operation of a relay agent, although this hook is not on the normal execution path. 943 - {peer} is the peer this message was previously sent to. 944 - {other} is NULL. 945 - {permsgdata} points to existing structure associated with this request. 919 946 */ 920 947 … … 923 950 -- parsing error 924 951 -- no remaining available peer for sending, based on routing callbacks decisions (maybe after retries). 925 - *msg points to the message. Again, the objects may not have been dictionary resolved. If you 926 try to call fd_msg_parse_dict, it might slow down the operation of a relay agent. 927 - *peer is NULL. 928 - *other is a char * pointer to the error message (human-readable). 952 - {msg} points to the message. Again, the objects may not have been dictionary resolved. If you 953 try to call fd_msg_parse_dict, it might slow down the operation of a relay agent, although this hook is not on the normal execution path. 954 - {peer} is NULL. 955 - {other} is a char * pointer to the error message (human-readable). 956 - {permsgdata} points to existing structure associated with this message (or new structure if no previous hook was registered). 929 957 */ 930 958 … … 933 961 The decision of knowing which peer it will be sent to is not made yet (or if an error will be returned). 934 962 The hook is trigged before the callbacks registered with fd_rt_fwd_register are called. 935 - *msg points to the message. Again, the objects may not have been dictionary resolved. If you 936 try to call fd_msg_parse_dict, it might slow down the operation of a relay agent. 937 - *peer is NULL. 938 - *other is NULL. 963 - {msg} points to the message. Again, the objects may not have been dictionary resolved. 964 If you try to call fd_msg_parse_dict, it will slow down the operation of a relay agent. 965 - {peer} is NULL. 966 - {other} is NULL. 967 - {permsgdata} points to existing structure associated with this message (or new structure if no previous hook was registered). 939 968 */ 940 969 941 970 HOOK_MESSAGE_ROUTING_LOCAL, 942 /* Hook called when a received message is handled locally by the routing_dispatch process .971 /* Hook called when a received message is handled locally by the routing_dispatch process (i.e., not forwarded). 943 972 The hook is trigged before the callbacks registered with fd_disp_register are called. 944 - *msg points to the message. Here, the message has been already parsed completely & successfully. 945 - *peer is NULL. 946 - *other is NULL. 973 - {msg} points to the message. Here, the message has been already parsed completely & successfully. 974 - {peer} is NULL. 975 - {other} is NULL. 976 - {permsgdata} points to existing structure associated with this message (or new structure if no previous hook was registered). 947 977 */ 948 978 … … 950 980 /* Hook called when a message is being discarded by the framework because of some error. 951 981 It is probably a good idea to log this for analysis. 952 - *msg points to the message. 953 - *peer is NULL. 954 - *other is a char * pointer to the error message (human-readable). 982 - {msg} points to the message, which will be freed as soon as the hook returns. 983 - {peer} is NULL. 984 - {other} is a char * pointer to the error message (human-readable). 985 - {permsgdata} points to existing structure associated with this message (or new structure if no previous hook was registered). 955 986 */ 956 987 957 988 HOOK_PEER_CONNECT_FAILED, 958 989 /* Hook called when a connection attempt to a remote peer has failed. 959 - *msg may be NULL (lower layer error, e.g. connection timeout) or points to the CEA message sent or received (with an error code). 960 - *peer may be NULL for incoming requests from unknown peers being rejected, otherwise it points to the peer structure associated with the attempt. 961 - *other is a char * pointer to the error message (human-readable). 990 - {msg} may be NULL (lower layer error, e.g. connection timeout) or points to the CEA message sent or received (with an error code). 991 - {peer} may be NULL for incoming requests from unknown peers being rejected, otherwise it points to the peer structure associated with the attempt. 992 - {other} is a char * pointer to the error message (human-readable). 993 - {permsgdata} is always NULL for this hook. 962 994 */ 963 995 964 996 HOOK_PEER_CONNECT_SUCCESS, 965 997 /* Hook called when a connection attempt to a remote peer has succeeded (the peer moves to OPEN state). 966 - *msg points to the CEA message sent or received (with an success code) -- in case it is sent, you can always get access to the matching CER. 967 - *peer points to the peer structure. 968 - *other is NULL. 998 - {msg} points to the CEA message sent or received (with an success code) -- in case it is sent, you can always get access to the matching CER. 999 - {peer} points to the peer structure. 1000 - {other} is NULL. 1001 - {permsgdata} is always NULL for this hook. 969 1002 */ 970 1003 1004 #define HOOK_PEER_LAST HOOK_PEER_CONNECT_SUCCESS 971 1005 }; 972 973 /* A handler associated with a registered callback, for cleanup */ 1006 1007 1008 /* Type if the {permsgdata} ointer. It is up to each extension to define its own structure. This is opaque for the framework. */ 1009 struct fd_hook_permsgdata; 1010 1011 /* A handle that will be associated with the extension, and with the permsgdata structures. */ 1012 struct fd_hook_data_hdl; 1013 1014 /* Function to register a new fd_hook_data_hdl. Should be called by your extension init function. 1015 * The arguments are the functions called to initialize a new fd_hook_permsgdata and to free this structure when the corresponding message is being freed. 1016 */ 1017 /* 1018 * FUNCTION: fd_hook_data_register 1019 * 1020 * PARAMETERS: 1021 * permsgdata_new_cb : function called to initialize a new empty fd_hook_permsgdata structure, when a hook will be called for a message with not structure yet. If the function returns NULL, it will be called again for the next hook. 1022 * permsgdata_destroy_cb : function called when a message is being disposed. It should free the resources associated with the fd_hook_permsgdata. 1023 * new_handle : On success, a handler to the registered callback is stored here. 1024 * This handler will be used to unregister the cb. 1025 * 1026 * DESCRIPTION: 1027 * Register a new fd_hook_data_hdl. This handle is used during hooks registration (see below) in order to associate data with the messages, to allow keeping tracking of the message easily. 1028 * Note that these handlers are statically allocated and cannot be unregistered. 1029 * 1030 * RETURN VALUE: 1031 * 0 : The callback is registered. 1032 * EINVAL : A parameter is invalid. 1033 * ENOSPC : Too many handles already registered. You may need to increase the limit in the code. 1034 */ 1035 int fd_hook_data_register( 1036 struct fd_hook_permsgdata * (*permsgdata_new_cb) (void), 1037 void (*permsgdata_destroy_cb) (struct fd_hook_permsgdata *), 1038 struct fd_hook_data_hdl ** new_handle 1039 ); 1040 1041 1042 /* A handler associated with a registered hook callback (for cleanup) */ 974 1043 struct fd_hook_hdl; 975 1044 … … 981 1050 * fd_hook_cb : The callback function to register (see prototype above). 982 1051 * regdata : Pointer to pass to the callback when it is called. The data is opaque to the daemon. 1052 * data_hdl : If permsgdata is requested for the hooks, a handler registered with fd_hook_data_register. NULL otherwise. 983 1053 * handler : On success, a handler to the registered callback is stored here. 984 * This handler willbe used to unregister the cb.985 * 986 * DESCRIPTION: 987 * Register a new hook in the framework. See explanations above.1054 * This handler can be used to unregister the cb. 1055 * 1056 * DESCRIPTION: 1057 * Register a new hook in the framework. See explanations above. 988 1058 * 989 1059 * RETURN VALUE: 990 1060 * 0 : The callback is registered. 1061 * EEXIST : Another callback is already registered for this type of hook (HOOK_DATA_RECEIVED). 991 1062 * EINVAL : A parameter is invalid. 992 1063 * ENOMEM : Not enough memory to complete the operation … … 994 1065 int fd_hook_register ( enum fd_hook_type type, 995 1066 void (*fd_hook_cb)(enum fd_hook_type type, struct msg * msg, struct peer_hdr * peer, void * other, void * regdata), 996 void * regdata, struct fd_hook_hdl ** handler ); 1067 void * regdata, 1068 struct fd_hook_data_hdl *data_hdl, 1069 struct fd_hook_hdl ** handler ); 997 1070 998 1071 /* Remove a hook registration */ … … 1000 1073 1001 1074 1075 /*============================================================*/ 1002 1076 1003 1077 /* … … 1043 1117 struct timespec * total, struct timespec * blocking, struct timespec * last); 1044 1118 1119 /*============================================================*/ 1120 /* EOF */ 1121 /*============================================================*/ 1122 1045 1123 #ifdef __cplusplus 1046 1124 }
Note: See TracChangeset
for help on using the changeset viewer.