diff options
author | Luis Ontanon <luis.ontanon@gmail.com> | 2013-06-21 01:27:28 +0000 |
---|---|---|
committer | Luis Ontanon <luis.ontanon@gmail.com> | 2013-06-21 01:27:28 +0000 |
commit | b5c96de50bedd0d944de415c3080e2aa278fc362 (patch) | |
tree | 826cfc10b7625d0c0e144bb1fef7c90d4d6b56be /echld/echld.h | |
parent | 74f0f96209400931e377c058efa186464dc09fd4 (diff) |
move echld to final dest...
svn path=/trunk/; revision=50102
Diffstat (limited to 'echld/echld.h')
-rw-r--r-- | echld/echld.h | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/echld/echld.h b/echld/echld.h new file mode 100644 index 0000000000..60b97d6f2e --- /dev/null +++ b/echld/echld.h @@ -0,0 +1,401 @@ +/* echld_child.h + * epan working child API + * + * $Id$ + * + * Wireshark - Network traffic analyzer + * By Gerald Combs <gerald@wireshark.org> + * Copyright 1998 Gerald Combs + * + * Copyright (c) 2013 by Luis Ontanon <luis@ontanon.org> + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License + * as published by the Free Software Foundation; either version 2 + * of the License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + */ + +#ifndef __ECHLD_H +#define __ECHLD_H + +#define ECHLD_VERSION "0.0" +#define ECHLD_MAJOR_VERSION 0 /* increases when existing things change */ + /* if this changes an old client may or may not work */ + +#define ECHLD_MINOR_VERSION 0 /* increases when new things are added */ + /* if just this one changes an old client will still work */ + +/* + * You should take a look to doc/README.epan_child before reading this + */ + +/* message types */ +typedef enum _echld_msg_type_t echld_msg_type_t; + +/* error types */ +typedef enum _echld_error echld_error_t; + +/* return codes */ + /* 0 is ok, everything else is ko, or timeout where applicable. */ +typedef int echld_state_t; +#define ECHLD_OK 0 +#define ECHLD_TIMEOUT -222 + +/* id for child working processes, a negative value is an error */ +typedef int echld_chld_id_t; + +/* id of requests, a negative value is an error */ +typedef int echld_reqh_id_t; + +/* id of message handlers, a negative value is an error */ +typedef int echld_msgh_id_t; + +/* sets the codec set by name */ +typedef enum _echld_encoding { + ECHLD_ENCODING_TEXT = 'T', + ECHLD_ENCODING_XML = 'X', + ECHLD_ENCODING_JSON = 'J' +} echld_encoding_t; + +typedef int echld_bool_t; + +/* typedef for a timeval so that sys/time.h is not required in the client */ +typedef struct timeval tv_t; + +/* will initialize epan registering protocols and taps */ +echld_state_t echld_initialize(echld_encoding_t); + +/* cleans up (?) echld and kills the server process(es) */ +echld_state_t echld_terminate(void); + +/* + * returning ECHLD_NO_ERROR means there has being no error + * + * errstr_ptr is a ptr to the error message string, will give NULL if no error + * usable only after the last API call, doesn't have to be freed. + * + * for managing asyncronous errors use a msgh for ECHLD_ERROR + * the response cb of reqh might be a ECHLD_ERROR message + */ +echld_error_t echld_get_error(const char** errstr_ptr); + +/* + * Children Management Operations + */ + +/* create a new worker process */ +echld_chld_id_t echld_new(void* child_data); + +/* will return NULL on error, if NULL is also ok for you use echld_get_error() */ +void* echld_get_data(echld_chld_id_t); + +echld_state_t echld_set_data(echld_chld_id_t id, void* child_data); + +/* for each child call cb(id,child_data,cb_data) */ +typedef echld_bool_t (*echld_iter_cb_t)(echld_chld_id_t, void* child_data, void* cb_data); +void echld_foreach_child(echld_iter_cb_t cb, void* cb_data); + +/* enc_msg_t is an obscure object for an encoded message */ +typedef struct GByteArray enc_msg_t; + + +/* + * prototype of message callbacks passed to echld_reqh() and echld_msgh() + * + * type: for reqh it might be ECHLD_ERROR, ECHLD_TIMEOUT or what you expect, + * in msgh it's always the message for which it was set + * msg_buff: the encoded message + * cb_data: arbitrary data passed by the user in echld_reqh() or echld_msgh() + * + * returns TRUE if other potential handlers are to be run, false otherwise + */ +typedef echld_bool_t (*echld_msg_cb_t)(echld_msg_type_t type, enc_msg_t* msg_buff, void* cb_data); + + + +/* encoding and decoding */ + + +/* + * encoder + * the enc_msg_t will be destroyed internally by the req handler + * the resulting enc_msg_t can be used in a reqh just once. + */ + +typedef struct _parent_out { + enc_msg_t* (*error)(int err, const char* text); + enc_msg_t* (*set_param)(const char* param, const char* value); + enc_msg_t* (*close_child)(int mode); + enc_msg_t* (*open_file)(const char* filename); + enc_msg_t* (*open_interface)(const char* intf_name, const char* params); + enc_msg_t* (*get_sum)(const char* range); + enc_msg_t* (*get_tree)(const char* range); + enc_msg_t* (*get_bufer)(const char* name); + enc_msg_t* (*add_note)(int packet_number, const char* note); + enc_msg_t* (*apply_filter)(const char* filter); + enc_msg_t* (*save_file)(const char* filename, const char* params); +} echld_parent_encoder_t; + +echld_parent_encoder_t* echld_get_encoder(); + +/* + * decoder + * it returns an allocated string with the decoded response of the message, you free it. + * it destroys the enc_msg_t as well. + */ +char* echld_decode(echld_msg_type_t, enc_msg_t*); + +/* + * Request Handlers + * + */ + +/* send a request with an optional response handler + * + * ba is a enc_msg_t that contains the encoded message + * resp_cb is the callback and cb_data the data it is going to be passed if executed + * + * returns the reqh id */ +echld_reqh_id_t echld_reqh(echld_chld_id_t, echld_msg_type_t, int usecs_timeout, enc_msg_t*, echld_msg_cb_t, void*); + +/* get callback data for a live request */ +void* echld_reqh_get_data(echld_chld_id_t, echld_reqh_id_t); + +/* get the total timeout time for a live request, -1 is err */ +int echld_reqh_get_to(echld_chld_id_t, echld_reqh_id_t); + +/* get the remaining timeout time for a live request, -1 is err */ +int echld_reqh_get_remaining_to(echld_chld_id_t, echld_reqh_id_t); + +/* get the callback for a live request */ +echld_msg_cb_t echld_reqh_get_cb(echld_chld_id_t, echld_reqh_id_t); + +/* set callback data for a live request */ +echld_state_t echld_reqh_set_data(echld_chld_id_t, echld_reqh_id_t, void* ); + +/* get the callback for a live request */ +echld_state_t echld_reqh_set_cb(echld_chld_id_t, echld_reqh_id_t, echld_msg_cb_t); + +/* stop receiving a live request */ +echld_state_t echld_reqh_detach(echld_chld_id_t, echld_reqh_id_t); + + +/* + * Message Handlers + * + */ + +/* start a message handler */ +echld_msgh_id_t echld_msgh(echld_chld_id_t, echld_msg_type_t, echld_msg_cb_t resp_cb, void* msg_data); + +/* stop it */ +echld_state_t echld_msgh_detach(echld_chld_id_t, echld_msgh_id_t); + +/* get a msgh's data */ +void* echld_msgh_get_data(echld_chld_id_t, echld_msgh_id_t); + +/* get a msgh's cb */ +echld_msg_cb_t echld_msgh_get_cb(echld_chld_id_t, echld_msgh_id_t); + +/* get a msgh's type */ +echld_msg_type_t echld_msgh_get_type(echld_chld_id_t, echld_msgh_id_t); + +/* get it all from a msgh */ +echld_state_t echld_msgh_get_all(echld_chld_id_t, int msgh_id, echld_msg_type_t*, echld_msg_cb_t*, void**); + +/* set a msgh's data */ +echld_state_t echld_msgh_set_data(echld_chld_id_t, int msgh_id, void* ); + +/* set a msgh's cb */ +echld_state_t echld_msgh_set_cb(echld_chld_id_t, int msgh_id, echld_msg_cb_t); + +/* set a msgh's type */ +echld_state_t echld_msgh_set_type(echld_chld_id_t, int msgh_id, echld_msg_type_t); + +/* set all elements of a msgh */ +echld_state_t echld_msgh_set_all(echld_chld_id_t, int msgh_id, echld_msg_type_t, echld_msg_cb_t, void*); + + +/* + * "Simple" API + * these calls require you looping on echld_select() or calling echld_wait() until you get your answer. + * see bellow + */ + +typedef void (*echld_ping_cb_t)(int usec, void* data); +echld_state_t echld_ping(int child_id, echld_ping_cb_t cb, void* cb_data); + +typedef void (*echld_list_interface_cb_t)(char* intf_name, char* params, void* cb_data); +echld_state_t echld_list_interfaces(int child_id, echld_list_interface_cb_t, void* cb_data); + +typedef void (*echild_get_packet_summary_cb_t)(char* summary, void* data); +echld_state_t echld_open_file(int child_id, const char* filename,echild_get_packet_summary_cb_t,void*); + + +echld_state_t echld_open_interface(int child_id, const char* intf_name, const char* params); +echld_state_t echld_start_capture(int child_id, echild_get_packet_summary_cb_t); +echld_state_t echld_stop_capture(int child_id); + +typedef void (*echild_get_packets_cb)(char* tree_text,void* data); +typedef void (*echild_get_buffer_cb)(char* buffer_text, void* data); +echld_state_t echld_get_packets_range(int child_id, const char* range, echild_get_packets_cb, echild_get_buffer_cb, void* data); + + +/* + * Server routines + */ + +/* + * waits until something gets done + * + * returns ECHLD_TIMEOUT or ECHLD_OK if something was done + */ +echld_state_t echld_wait(tv_t* timeout); + +#define ECHLD_WAIT() do { struct timeval tv; int rfds, efds; \ + echld_select(echld_fdset(&rfds, &efds),&rfds, NULL, &efds, NULL) \ + && echld_fd_read(&rfds, &efds); } while(0) + +/* + to be used in place of select() in the main loop of the parent code + it will serve the children pipes and return as if select() was called. +*/ +int echld_select(int nfds, fd_set* rfds, fd_set* wfds, fd_set* efds, tv_t* timeout); + +/* or fit these two in your select loop */ + +/* returns nfds set */ +int echld_fdset(fd_set* rfds, fd_set* efds); + +int echld_fd_read(fd_set* rfds, fd_set* efds); + +void echld_set_parent_dbg_level(int lvl); + + +#define ECHLD_MAX_CHILDREN 32 + +enum _echld_msg_type_t { + /* in = child to parent */ + /* out = parent to child */ + + ECHLD_ERROR = '!', /* in: an error has occurred, + * this can be a response to most messages + * some errors are sent asyncronously (some are handled internally, some are then passed) + */ + ECHLD_TIMED_OUT='/', /* in: A reqh has timed out (TO from now on) + * this can be a response to some messages + * some TOs are sent asyncronously (some are handled internally, some are then passed) + */ + + ECHLD_NEW_CHILD = '*', /* out: creates a new working child (handled internally) */ + ECHLD_HELLO = '@', /* in: the working child has being created (handled internally, then passed to msgh) */ + + ECHLD_CHILD_DEAD = '#', /* in: a child has dead (handled internally, then passed to msgh) */ + + ECHLD_CLOSE_CHILD = 'Q', /* out: close the child */ + ECHLD_CLOSING = 'q', /* in: the child is closing, error otherwise */ + /* this handled internally as msgh, if your reqh_cb uses it make sure to return TRUE */ + + ECHLD_SET_PARAM = '>', /* out: set a parameter of a child */ + ECHLD_GET_PARAM = '<', /* out: set a parameter of a child */ + ECHLD_PARAM = 'p', /* in: the parameter's new/current value, error otherwise */ + + /* capture_filter string RO: set at open_capture */ + /* monitor_mode string RW: use monitor mode if possible, error otherwise */ + /* inc_pkt_ntfy_timeout number_string RW: timeout in usec after which notification is sent if no maxpackets have arrived yet */ + /* inc_pkt_ntfy_maxpackets number_string RW: number of packets after which send a notification */ + /* auto_sum RW: get summaries automatically (without a reqh, as msgh) */ + /* auto_tree RW: get trees automatically (without a reqh, as msgh) */ + /* auto_buffer RW: get buffers automatically (without a reqh, as msgh) */ + /* cwd RW: the current working directory */ + /* list_files WO: a file listing of the current dir */ + /* interfaces RO: the interface listing */ + /* dfilter RW: initial display filter* + /* ... */ + + ECHLD_PING = '}', /* out: ping the child */ + ECHLD_PONG = '{', /* out: ping's response, error or TO otherwise */ + + ECHLD_CHK_FILTER = 'K', /* out: verify if a (display) filter works */ + ECHLD_FILTER_CKD = 'k', /* in: yes this filter works, error or TO? otherwise */ + + ECHLD_OPEN_FILE = 'O', /* out: open a file */ + ECHLD_FILE_OPENED = 'o', /* in: the file has being open, error otherwise */ + + ECHLD_OPEN_INTERFACE = 'C', /* out: request an interface to be open (get ready for capture) */ + ECHLD_INTERFACE_OPENED = 'c', /* in: ready to start_capture, error otherwise */ + + ECHLD_START_CAPTURE = 'R', /* out: start capturing */ + ECHLD_CAPTURE_STARTED = 'r', /* in: the capture has started, error otherwise */ + + ECHLD_NOTIFY = '%', /* in: many things can be notified by the child: + number of packets captured/read + other events in the future (?) + */ + + ECHLD_GET_SUM = 'S', /* out: get the summaries of a range of packets (even before they are notify'd) */ + ECHLD_PACKET_SUM = 's', /* in: a packet's summary (when it arrives for a reqh) (in msgh if auto_sum )*/ + /* no timeout, the request hangs until the packets in the range are available */ + /* error at EOF or CAPTURE_STOPPED if the request is still hanging */ + + ECHLD_GET_TREE = 'G', /* out: get the decoded version of the packet */ + ECHLD_TREE = 't', /* Child -> Parent */ + /* no timeout, the request hangs until the packets in the range are available */ + /* error at EOF or CAPTURE_STOPPED if the request is still hanging */ + + + ECHLD_GET_BUFFER = 'B', /* out: get the decoded version of the packet */ + ECHLD_BUFFER = 'b', /* in: get a buffer (or what we have of it... or the next part... same reqh_id) */ + /* no timeout, the request hangs until the packets in the range are available */ + /* error at EOF or CAPTURE_STOPPED if the request is still hanging */ + + ECHLD_EOF = 'z', /* in: will be delivered when a file has being read and all pendin ntfy,sums,trees and buffs have being passed + or after capture has stopped and all pending stuff is done */ + + ECHLD_STOP_CAPTURE = 'X', /* out: stop capturing */ + ECHLD_CAPTURE_STOPPED = 'x', /* in: capture has stopped, error otherwise */ + + ECHLD_ADD_NOTE = 'N', /* out: add a note to the capture */ + ECHLD_NOTE_ADDED = 'n', /* in: a note has being added */ + + ECHLD_APPLY_FILTER = 'A', /* in: apply a filter on the open file/capture */ + ECHLD_PACKET_LIST = 'l', /* out: a packet list, or error or timeout */ + /*(or what we have of it... or the next part... same reqh_id) */ + + ECHLD_SAVE_FILE = 'W', /* out: save the open file/capture */ + ECHLD_FILE_SAVED = 'w', /* in: the file was saved */ + + + EC_ACTUAL_ERROR = 0 /* this is not used in the protocol, + it is returned for an error in calls returning a message type */ +}; + +enum _echld_error { + ECHLD_NO_ERROR = 0, + ECHLD_ERR_UNIMPLEMENTED, + ECHLD_ERR_WRONG_MSG, + ECHLD_ERR_NO_SUCH_CHILD, + ECHLD_ERR_UNKNOWN_PID, + ECHLD_ERR_CANNOT_FORK, + ECHLD_ERR_SET_FILTER, + ECHLD_ERR_CANNOT_OPEN_FILE, + ECHLD_ERR_CANNOT_OPEN_INTERFACE, + ECHLD_ERR_CANNOT_START_CAPTURE, + ECHLD_ERR_CANNOT_LIST_INTERFACES, + ECHLD_CANNOT_SET_PARAM, + ECHLD_CANNOT_GET_PARAM, + ECHLD_ERR_CRASHED_CHILD, + ECHLD_ERR_OTHER +}; + + +#endif |