A further iteration on epan_child

svn path=/trunk/; revision=49849

1 files changed, 253 insertions, 0 deletions

diff --git a/doc/README.epan_child b/doc/README.epan_child
new file mode 100644
index 0000000000..bc0ea3ca81
--- /dev/null
+++ b/doc/README.epan_child
@@ -0,0 +1,253 @@
+EPAN CHILDREN
+
+  $ Id: $
+  
+  This document is a work in progress.
+
+  This document describes a potential interface between a master process and one or more working children.
+  The goal is to have along-running epan process without the troubles of epan reinit (leaks, mis-reinits, ...).
+  Working children are spawn to capture or read files, then terminated.
+  The long running parent process initializes epan and forks children that require no further initialization to run.
+
+  epan_child.h in the root directory describes the C interface.
+
+
+Appendix A
+ECHLD PROTOCOL INTERACTION DIAGRAMS
+
+        parent            child            dumpcap
+          |                 |                 | 
+
+
+A.1. creation
+     new_child() ---------->|
+          |<-----HELLO------|
+                          IDLE
+
+
+A.2. keepalive
+A.2.1 p->c
+                        ANY_STATE
+          |-------PING----->|
+          |<------PONG------|
+                        SAME_STATE
+A.2.2 c->p
+                        ANY_STATE
+          |<------PING------|
+          |-------PONG----->|
+                        SAME_STATE
+
+
+A.3. destruction
+A.3.1 normal
+                        ANY_STATE
+          |---CLOSE_CHILD-->|
+          |<----CLOSING-----|
+                          DYING
+          |<-- SIG_CHLD
+     delete_child()
+
+A.3.2 fatal error
+                        ANY_STATE
+          |<-----ERROR------| (fatal_err,"reason")
+          |<---SIG_CHLD
+     delete_child()
+
+A.3.3 crash
+                        ANY_STATE
+          |<---SIG_CHLD
+     delete_child()
+
+
+
+A.4. getting current dir
+                        ANY_STATE
+          |-------PWD------>|
+          |<------CWD-------| (dirname)
+                        SAME_STATE
+
+
+A.5. changing current dir
+A.5.1 dir changed ok
+                        ANY_STATE
+          |------CHDIR----->| (dirname)
+          |<------CWD-------| (dirname)
+                        SAME_STATE
+A.5.2 dir changed ko
+                        ANY_STATE
+          |------CHDIR----->| (dirname)
+          |<-----ERROR------| (cannot_cd, "reason")
+                        SAME_STATE
+
+A.6. listing current directory
+A.6.1 file list ok
+                        ANY_STATE
+          |----LIST_FILES-->| ("*.*"")
+          |<---FILE_INFO----| (filename, format,  encap, num_pkts, ...);
+          |<---FILE_INFO----| (filename, format,  encap, num_pkts, ...);
+          .....
+          |<---FILE_INFO----| (filename, format,  encap, num_pkts, ...);
+                        SAME_STATE
+A.6.2 file list ko
+                        ANY_STATE
+          |----LIST_FILES-->| ("*.*"")
+          |<-----ERROR------| (no_files, "reason")
+                        SAME_STATE
+
+
+A.7. opening a file
+A.7.1 opened ok
+                            IDLE
+          |----OPEN_FILE---->| (filename, ...)
+          |<---FILE_OPENED---| (dirname)
+                          READING
+A.7.2 not opened
+                            IDLE
+          |----OPEN_FILE---->| (filename, ...)
+          |<-----ERROR-------| (cannot_open, "reason")
+                            IDLE
+
+
+A.8. saving a file
+A.8.1 save ok
+                    READING/CAPTURING/DONE
+          |-----SAVE_FILE---->| ("new_filename",opts,...)
+          |<----FILE_SAVED----| (24, tree)
+                          SAME_STATE
+
+A.8.1 save ko
+                    READING/CAPTURING/DONE
+          |-----SAVE_FILE---->| ("new_filename",opts,...)
+          |<------ERROR-------| (cannot_save, "reason")
+                          SAME_STATE
+
+
+A.9. listing interfaces
+A.9.1 intf list ok
+                              IDLE
+          |--LIST_INTERFACES-->| ("*.*"")
+          |                    |-------????------>|
+          |                    |<------????-------|
+          |<--INTERFACE_INFO---| (name, param1=val1, ...)
+          |<--INTERFACE_INFO---| (name, param1=val1, ...)
+          .....
+          |<--INTERFACE_INFO---| (name, param1=val1, ...)
+                              IDLE
+A.9.2 intf list ko
+          |--LIST_INTERFACES-->| ("*.*"")
+          |                    |-------????------>|
+          |                    |<------????-------|
+          |<------ERROR-------| (list_intf, "reason")
+
+
+A.10. opening an interface
+A.10.1 interface opened ok
+                              IDLE
+          |---OPEN_INTERFACE-->|
+          |                    |-------????------>|
+          |                    |<------????-------|
+          |<--INTERFACE_OPENED-|
+                              READY
+
+A.10.2 interface open failure
+                              IDLE
+          |--OPEN_INTERFACE--->|
+          |                    |-------????------>|
+          |                    |<------????-------|
+          |<-------ERROR-------| (intf, "reason")
+                              IDLE
+
+
+A.11. starting capture
+A.11.1 started capture ok
+                             READY
+          |---START_CAPTURE--->|
+          |                    |-------????------>|
+          |                    |<------????-------|
+          |<-CAPTURE_STARTED---|
+                             IN_CAPTURE
+A.11.2 capture start failure
+                             READY
+          |----START_CAPTURE-->|
+          |                    |-------????------>|
+          |                    |<------????-------|
+          |<-------ERROR-------| (cannot_start, "reason")
+                             READY
+
+A.12. capturing or reading
+                       IN_CAPTURE/READING
+          |                    |<------????-------|
+          |<----PACKET_SUM-----| (framenum, columns)
+                          IN_CAPTURE
+
+A.13 getting packet details
+A.13.1 just frame
+                       IN_CAPTURE/READING
+          |----GET_PACKETS--->| (framelist)
+          |<-----PACKET-------| (1, tree)
+          |<-----BUFFER-------| ("1", tvb)
+          |<-----PACKET-------| (2, tree)
+          |<-----BUFFER-------| ("2", tvb)
+                          SAME_STATE
+
+A.13.2 frame with reassembled buffer
+                       IN_CAPTURE/READING/DONE
+          |----GET_PACKETS--->| (framelist)
+          |<-----PACKET-------| (framenum, tree)
+          |<-----BUFFER-------| ("framenum", tvb)
+          |<-----BUFFER-------| ("reas_num", tvb)
+                          SAME_STATE
+
+
+A.13.3 frame with known reassembled buffer
+                       IN_CAPTURE/READING/DONE
+          |<-----PACKET-------| (framenum+N, tree)
+          |<-----BUFFER-------| ("framenum+N", tvb)
+          |<-----BUFFER-------| ("reas_num", NULL)
+                          SAME_STATE
+
+A.13.4 buffer request (e.g. un-cached buffer)
+                       IN_CAPTURE/READING/DONE
+          |------GET_BUF----->| (bufname)
+          |<-----BUFFER-------| (bufname, NULL)
+                          SAME_STATE
+
+A.14 stpping capture
+                          IN_CAPTURE
+          |---STOP_CAPTURE--->|
+          |<-CAPTURE_STOPPED--|
+                             DONE
+
+
+A.15. done reading
+                            READING
+                               |<-- EOF
+          |<--------EOF--------|
+                             DONE
+
+A.16 setting a note
+A.16.1 note set ok
+                       IN_CAPTURE/READING/DONE
+          |----ADD_NOTE------>| (framenum,note)
+          |<----NOTE_ADDED----|
+                          SAME_STATE
+A.16.2 note set failure
+                       IN_CAPTURE/READING/DONE
+          |----ADD_NOTE------>| (framenum,note)
+          |<----NOTE_ADDED----|
+                          SAME_STATE
+
+A.17 applying a filter
+                       IN_CAPTURE/READING/DONE
+          |---APPLY_FILTER--->| (dfilter_str)
+          |<---PACKET_LIST----| (Packet-Range)
+          |<---PACKET_LIST----| (Packet-Range)
+                          SAME_STATE
+
+
+A.17 applying a filter
+                             IDLE
+          |---APPLY_FILTER---->| (dfilter_str)
+          |<---FILTER_SET------|
+                             IDLE
+