doc/README.epan_child

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