Mercurial > hg > freeDiameter

comparison include/freeDiameter/libfdcore.h @ 1069:544fa1be79a9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Update the new API prototype to make it easier for extension to track messages between hooks, for e.g. timing computations
author Sebastien Decugis <sdecugis@freediameter.net>
date Tue, 30 Apr 2013 12:09:32 +0800
parents 23989d6c8390
children 6ca6cadf209c
comparison
equal deleted inserted replaced
1068:54f06e95c2ee 1069:544fa1be79a9
871 * PARAMETERS: 871 * PARAMETERS:
872 * type : The type of hook that triggered this call, in case same cb is registered for several hooks. 872 * type : The type of hook that triggered this call, in case same cb is registered for several hooks.
873 * msg : If relevant, the pointer to the message trigging the call. NULL otherwise. 873 * msg : If relevant, the pointer to the message trigging the call. NULL otherwise.
874 * peer : If relevant, the pointer to the peer associated with the call. NULL otherwise. 874 * peer : If relevant, the pointer to the peer associated with the call. NULL otherwise.
875 * other : For some callbacks, the remaining information is passed in this parameter. See each hook detail. 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 * regdata : Data pointer stored at registration, opaque for the framework. 880 * regdata : Data pointer stored at registration, opaque for the framework.
877 * 881 *
878 * DESCRIPTION: 882 * DESCRIPTION:
879 * When such callback is registered with fd_hook_register function, it will be called on matching events with 883 * When such callback is registered with fd_hook_register function, it will be called on matching events with
880 * the parameters as described in the list of fd_hook_type below. One can use this mechanism for e.g.: 884 * the parameters as described in the list of fd_hook_type below. One can use this mechanism for e.g.:
881 * - log completely the messages for safety / backup 885 * - log completely the messages for safety / backup
882 * - create statistics information on the throughput 886 * - create statistics information on the throughput
883 * - ... 887 * - ...
884 * 888 *
885 * IMPORTANT: the callback MUST NOT change the momory 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 * RETURN VALUE: 891 * RETURN VALUE:
888 * none. 892 * none.
889 */ 893 */
890 894
891 /* The available hooks in the framework */ 895 /* The available hooks in the framework */
892 enum fd_hook_type { 896 enum fd_hook_type {
893 897
894 HOOK_MESSAGE_RECEIVED = 1, 898 HOOK_DATA_RECEIVED = 0,
895 /* Hook called when a message has been received and the structure has been parsed successfully (list of AVPs). 899 /* Hook called as soon as a message has been received from the network, after TLS & boundary processing.
896 - *msg points to the parsed message. At this time, the objects have not been dictionary resolved. If you 900 - {msg} is NULL.
897 try to call fd_msg_parse_dict, it might slow down the operation of a relay agent. 901 - {peer} is NULL.
898 - *peer is set if the message is received from a peer's connection, and NULL if the message is from a new client 902 - {*other} is NULL, {other} points to a valid location where you can store a pointer.
899 connected and not yet identified 903 This same pointer will then passed to the next hook, once message is processed.
900 - *other is NULL. 904 IMPORTANT: free() will be called on this pointer if any problem, so this pointer must be malloc'd.
901 */ 905 - {permsgdata} is NULL.
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: { .
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 HOOK_MESSAGE_SENT, 926 HOOK_MESSAGE_SENT,
912 /* Hook called when a message has been sent to a peer. The message might be freed as soon as the hook function returns, 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 so it is not safe to store the pointer for asynchronous processing. 928 so it is not safe to store the pointer for asynchronous processing.
914 - *msg points to the sent message. Again, the objects may not have been dictionary resolved. If you 929 - {msg} points to the sent message. Again, the objects may not have been dictionary resolved. If you
915 try to call fd_msg_parse_dict, it might slow down the operation of a relay agent. 930 try to call fd_msg_parse_dict, it will slow down the operation of a relay agent.
916 - *peer is set if the message is sent to a peer's connection, and NULL if the message is sent to a new client 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 connected and not yet identified / being rejected 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
921 HOOK_MESSAGE_ROUTING_ERROR, 948 HOOK_MESSAGE_ROUTING_ERROR,
922 /* Hook called when a message being processed by the routing thread meets an error such as: 949 /* Hook called when a message being processed by the routing thread meets an error such as:
923 -- parsing error 950 -- parsing error
924 -- no remaining available peer for sending, based on routing callbacks decisions (maybe after retries). 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 952 - {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. 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.
927 - *peer is NULL. 954 - {peer} is NULL.
928 - *other is a char * pointer to the error message (human-readable). 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
931 HOOK_MESSAGE_ROUTING_FORWARD, 959 HOOK_MESSAGE_ROUTING_FORWARD,
932 /* Hook called when a received message is deemed to be not handled locally by the routing_dispatch process. 960 /* Hook called when a received message is deemed to be not handled locally by the routing_dispatch process.
933 The decision of knowing which peer it will be sent to is not made yet (or if an error will be returned). 961 The decision of knowing which peer it will be sent to is not made yet (or if an error will be returned).
934 The hook is trigged before the callbacks registered with fd_rt_fwd_register are called. 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 963 - {msg} points to the message. Again, the objects may not have been dictionary resolved.
936 try to call fd_msg_parse_dict, it might slow down the operation of a relay agent. 964 If you try to call fd_msg_parse_dict, it will slow down the operation of a relay agent.
937 - *peer is NULL. 965 - {peer} is NULL.
938 - *other 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 HOOK_MESSAGE_ROUTING_LOCAL, 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 The hook is trigged before the callbacks registered with fd_disp_register are called. 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. 973 - {msg} points to the message. Here, the message has been already parsed completely & successfully.
945 - *peer is NULL. 974 - {peer} is NULL.
946 - *other 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
949 HOOK_MESSAGE_DROPPED, 979 HOOK_MESSAGE_DROPPED,
950 /* Hook called when a message is being discarded by the framework because of some error. 980 /* Hook called when a message is being discarded by the framework because of some error.
951 It is probably a good idea to log this for analysis. 981 It is probably a good idea to log this for analysis.
952 - *msg points to the message. 982 - {msg} points to the message, which will be freed as soon as the hook returns.
953 - *peer is NULL. 983 - {peer} is NULL.
954 - *other is a char * pointer to the error message (human-readable). 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 HOOK_PEER_CONNECT_FAILED, 988 HOOK_PEER_CONNECT_FAILED,
958 /* Hook called when a connection attempt to a remote peer has failed. 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). 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).
960 - *peer may be NULL for incoming requests from unknown peers being rejected, otherwise it points to the peer structure associated with the attempt. 991 - {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). 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 HOOK_PEER_CONNECT_SUCCESS, 996 HOOK_PEER_CONNECT_SUCCESS,
965 /* Hook called when a connection attempt to a remote peer has succeeded (the peer moves to OPEN state). 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. 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.
967 - *peer points to the peer structure. 999 - {peer} points to the peer structure.
968 - *other is NULL. 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 1006
973 /* A handler associated with a registered callback, for cleanup */ 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 struct fd_hook_hdl; 1043 struct fd_hook_hdl;
975 1044
976 /* 1045 /*
977 * FUNCTION: fd_hook_register 1046 * FUNCTION: fd_hook_register
978 * 1047 *
979 * PARAMETERS: 1048 * PARAMETERS:
980 * type : The fd_hook_type for which this cb is registered. Call several times if you want to register for several hooks. 1049 * type : The fd_hook_type for which this cb is registered. Call several times if you want to register for several hooks.
981 * fd_hook_cb : The callback function to register (see prototype above). 1050 * fd_hook_cb : The callback function to register (see prototype above).
982 * regdata : Pointer to pass to the callback when it is called. The data is opaque to the daemon. 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 * handler : On success, a handler to the registered callback is stored here. 1053 * handler : On success, a handler to the registered callback is stored here.
984 * This handler will be used to unregister the cb. 1054 * This handler can be used to unregister the cb.
985 * 1055 *
986 * DESCRIPTION: 1056 * DESCRIPTION:
987 * Register a new hookin the framework. See explanations above. 1057 * Register a new hook in the framework. See explanations above.
988 * 1058 *
989 * RETURN VALUE: 1059 * RETURN VALUE:
990 * 0 : The callback is registered. 1060 * 0 : The callback is registered.
1061 * EEXIST : Another callback is already registered for this type of hook (HOOK_DATA_RECEIVED).
991 * EINVAL : A parameter is invalid. 1062 * EINVAL : A parameter is invalid.
992 * ENOMEM : Not enough memory to complete the operation 1063 * ENOMEM : Not enough memory to complete the operation
993 */ 1064 */
994 int fd_hook_register ( enum fd_hook_type type, 1065 int fd_hook_register ( enum fd_hook_type type,
995 void (*fd_hook_cb)(enum fd_hook_type type, struct msg * msg, struct peer_hdr * peer, void * other, void * regdata), 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 /* Remove a hook registration */ 1071 /* Remove a hook registration */
999 int fd_hook_unregister( struct fd_hook_hdl * handler ); 1072 int fd_hook_unregister( struct fd_hook_hdl * handler );
1000 1073
1001 1074
1075 /*============================================================*/
1002 1076
1003 /* 1077 /*
1004 * The following allows an extension to retrieve stat information on the different fifo queues involved in the freeDiameter framework. 1078 * The following allows an extension to retrieve stat information on the different fifo queues involved in the freeDiameter framework.
1005 * There are three global queues, plus per-peer queues. 1079 * There are three global queues, plus per-peer queues.
1006 * This information can be used to build SNMP-like data for example, or quickly get a status of the framework to find the loaded path of execution / bottlenecks. 1080 * This information can be used to build SNMP-like data for example, or quickly get a status of the framework to find the loaded path of execution / bottlenecks.
1040 */ 1114 */
1041 int fd_stat_getstats(enum fd_stat_type stat, struct peer_hdr * peer, 1115 int fd_stat_getstats(enum fd_stat_type stat, struct peer_hdr * peer,
1042 int * len, int * max, int * highest_count, long long * total_count, 1116 int * len, int * max, int * highest_count, long long * total_count,
1043 struct timespec * total, struct timespec * blocking, struct timespec * last); 1117 struct timespec * total, struct timespec * blocking, struct timespec * last);
1044 1118
1119 /*============================================================*/
1120 /* EOF */
1121 /*============================================================*/
1122
1045 #ifdef __cplusplus 1123 #ifdef __cplusplus
1046 } 1124 }
1047 #endif 1125 #endif
1048 1126
1049 #endif /* _LIBFDCORE_H */ 1127 #endif /* _LIBFDCORE_H */
"Welcome to our mercurial repository"