doc/README.epan_child

   1 EPAN CHILDREN
   2
   3   This document is a work in progress.
   4
   5   This document describes a potential interface between a master process and one or more working children.
   6   The goal is to have along-running epan process without the troubles of epan reinit (leaks, mis-reinits, ...).
   7   Working children are spawn to capture or read files, then terminated.
   8   The long running parent process initializes epan and forks children that require no further initialization to run.
   9
  10   epan_child.h in the root directory describes the C interface.
  11
  12
  13 Appendix A
  14 ECHLD PROTOCOL INTERACTION DIAGRAMS
  15
  16         parent            child            dumpcap
  17           |                 |                 |
  18
  19
  20 A.1. creation
  21      new_child() ---------->|
  22           |<-----HELLO------|
  23                           IDLE
  24
  25
  26 A.2. keepalive
  27 A.2.1 p->c
  28                         ANY_STATE
  29           |-------PING----->|
  30           |<------PONG------|
  31                         SAME_STATE
  32 A.2.2 c->p
  33                         ANY_STATE
  34           |<------PING------|
  35           |-------PONG----->|
  36                         SAME_STATE
  37
  38
  39 A.3. destruction
  40 A.3.1 normal
  41                         ANY_STATE
  42           |---CLOSE_CHILD-->|
  43           |<----CLOSING-----|
  44                           DYING
  45           |<-- SIG_CHLD
  46      delete_child()
  47
  48 A.3.2 fatal error
  49                         ANY_STATE
  50           |<-----ERROR------| (fatal_err,"reason")
  51           |<---SIG_CHLD
  52      delete_child()
  53
  54 A.3.3 crash
  55                         ANY_STATE
  56           |<---SIG_CHLD
  57      delete_child()
  58
  59
  60
  61 A.4. getting current dir
  62                         ANY_STATE
  63           |-------PWD------>|
  64           |<------CWD-------| (dirname)
  65                         SAME_STATE
  66
  67
  68 A.5. changing current dir
  69 A.5.1 dir changed ok
  70                         ANY_STATE
  71           |------CHDIR----->| (dirname)
  72           |<------CWD-------| (dirname)
  73                         SAME_STATE
  74 A.5.2 dir changed ko
  75                         ANY_STATE
  76           |------CHDIR----->| (dirname)
  77           |<-----ERROR------| (cannot_cd, "reason")
  78                         SAME_STATE
  79
  80 A.6. listing current directory
  81 A.6.1 file list ok
  82                         ANY_STATE
  83           |----LIST_FILES-->| ("*.*"")
  84           |<---FILE_INFO----| (filename, format,  encap, num_pkts, ...);
  85           |<---FILE_INFO----| (filename, format,  encap, num_pkts, ...);
  86           .....
  87           |<---FILE_INFO----| (filename, format,  encap, num_pkts, ...);
  88                         SAME_STATE
  89 A.6.2 file list ko
  90                         ANY_STATE
  91           |----LIST_FILES-->| ("*.*"")
  92           |<-----ERROR------| (no_files, "reason")
  93                         SAME_STATE
  94
  95
  96 A.7. opening a file
  97 A.7.1 opened ok
  98                             IDLE
  99           |----OPEN_FILE---->| (filename, ...)
 100           |<---FILE_OPENED---| (dirname)
 101                           READING
 102 A.7.2 not opened
 103                             IDLE
 104           |----OPEN_FILE---->| (filename, ...)
 105           |<-----ERROR-------| (cannot_open, "reason")
 106                             IDLE
 107
 108
 109 A.8. saving a file
 110 A.8.1 save ok
 111                     READING/CAPTURING/DONE
 112           |-----SAVE_FILE---->| ("new_filename",opts,...)
 113           |<----FILE_SAVED----| (24, tree)
 114                           SAME_STATE
 115
 116 A.8.1 save ko
 117                     READING/CAPTURING/DONE
 118           |-----SAVE_FILE---->| ("new_filename",opts,...)
 119           |<------ERROR-------| (cannot_save, "reason")
 120                           SAME_STATE
 121
 122
 123 A.9. listing interfaces
 124 A.9.1 intf list ok
 125                               IDLE
 126           |--LIST_INTERFACES-->| ("*.*"")
 127           |                    |-------????------>|
 128           |                    |<------????-------|
 129           |<--INTERFACE_INFO---| (name, param1=val1, ...)
 130           |<--INTERFACE_INFO---| (name, param1=val1, ...)
 131           .....
 132           |<--INTERFACE_INFO---| (name, param1=val1, ...)
 133                               IDLE
 134 A.9.2 intf list ko
 135           |--LIST_INTERFACES-->| ("*.*"")
 136           |                    |-------????------>|
 137           |                    |<------????-------|
 138           |<------ERROR-------| (list_intf, "reason")
 139
 140
 141 A.10. opening an interface
 142 A.10.1 interface opened ok
 143                               IDLE
 144           |---OPEN_INTERFACE-->|
 145           |                    |-------????------>|
 146           |                    |<------????-------|
 147           |<--INTERFACE_OPENED-|
 148                               READY
 149
 150 A.10.2 interface open failure
 151                               IDLE
 152           |--OPEN_INTERFACE--->|
 153           |                    |-------????------>|
 154           |                    |<------????-------|
 155           |<-------ERROR-------| (intf, "reason")
 156                               IDLE
 157
 158
 159 A.11. starting capture
 160 A.11.1 started capture ok
 161                              READY
 162           |---START_CAPTURE--->|
 163           |                    |-------????------>|
 164           |                    |<------????-------|
 165           |<-CAPTURE_STARTED---|
 166                              IN_CAPTURE
 167 A.11.2 capture start failure
 168                              READY
 169           |----START_CAPTURE-->|
 170           |                    |-------????------>|
 171           |                    |<------????-------|
 172           |<-------ERROR-------| (cannot_start, "reason")
 173                              READY
 174
 175 A.12. capturing or reading
 176                        IN_CAPTURE/READING
 177           |                    |<------????-------|
 178           |<----PACKET_SUM-----| (framenum, columns)
 179                           IN_CAPTURE
 180
 181 A.13 getting packet details
 182 A.13.1 just frame
 183                        IN_CAPTURE/READING
 184           |----GET_PACKETS--->| (framelist)
 185           |<-----PACKET-------| (1, tree)
 186           |<-----BUFFER-------| ("1", tvb)
 187           |<-----PACKET-------| (2, tree)
 188           |<-----BUFFER-------| ("2", tvb)
 189                           SAME_STATE
 190
 191 A.13.2 frame with reassembled buffer
 192                        IN_CAPTURE/READING/DONE
 193           |----GET_PACKETS--->| (framelist)
 194           |<-----PACKET-------| (framenum, tree)
 195           |<-----BUFFER-------| ("framenum", tvb)
 196           |<-----BUFFER-------| ("reas_num", tvb)
 197                           SAME_STATE
 198
 199
 200 A.13.3 frame with known reassembled buffer
 201                        IN_CAPTURE/READING/DONE
 202           |<-----PACKET-------| (framenum+N, tree)
 203           |<-----BUFFER-------| ("framenum+N", tvb)
 204           |<-----BUFFER-------| ("reas_num", NULL)
 205                           SAME_STATE
 206
 207 A.13.4 buffer request (e.g. un-cached buffer)
 208                        IN_CAPTURE/READING/DONE
 209           |------GET_BUF----->| (bufname)
 210           |<-----BUFFER-------| (bufname, NULL)
 211                           SAME_STATE
 212
 213 A.14 stpping capture
 214                           IN_CAPTURE
 215           |---STOP_CAPTURE--->|
 216           |<-CAPTURE_STOPPED--|
 217                              DONE
 218
 219
 220 A.15. done reading
 221                             READING
 222                                |<-- EOF
 223           |<--------EOF--------|
 224                              DONE
 225
 226 A.16 setting a note
 227 A.16.1 note set ok
 228                        IN_CAPTURE/READING/DONE
 229           |----ADD_NOTE------>| (framenum,note)
 230           |<----NOTE_ADDED----|
 231                           SAME_STATE
 232 A.16.2 note set failure
 233                        IN_CAPTURE/READING/DONE
 234           |----ADD_NOTE------>| (framenum,note)
 235           |<----NOTE_ADDED----|
 236                           SAME_STATE
 237
 238 A.17 applying a filter
 239                        IN_CAPTURE/READING/DONE
 240           |---APPLY_FILTER--->| (dfilter_str)
 241           |<---PACKET_LIST----| (Packet-Range)
 242           |<---PACKET_LIST----| (Packet-Range)
 243                           SAME_STATE
 244
 245
 246 A.18 setting a filter
 247                              IDLE
 248           |-----SET_FILTER---->| (dfilter_str)
 249           |<---FILTER_SET------|
 250                              IDLE
 251