EPAN CHILDREN

  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.18 setting a filter
                             IDLE
          |-----SET_FILTER---->| (dfilter_str)
          |<---FILTER_SET------|
                             IDLE