badcc8fba2
Development.md describes the wire-layer convention (one directory per Onvif Web Service, gen_commands.py for new SOAP command types) but does not mention that some directories also ship hand-written higher-level helpers built on top of those types. A new contributor reading the doc could reasonably assume event/ is purely auto-generated and miss event/stream. Adds a 'Higher-level helpers' section that calls out: * event/stream — the new channel-based event consumer. * event/topic — the existing topic identifier helpers. Also documents the placement convention (sub-package under the relevant web service directory) so future helpers land in a predictable spot.
2.4 KiB
Development
Onvif Command Support
Each of the following Onvif Web services has its own directory:
Inside each directory there is:
types.go: contains the struct definitions for each onvif command and responsefunction.go: contains the auto-generated types that implement theFunctioninterface providingRequest()andResponse()type mappings.
At the root level there is:
- names.go: contains the auto-generated constant names of all the commands
- mappings.go: contains the auto-generated mappings for each Onvif WebService from function name to function datatype
Adding support for additional commands
Note: Currently, the python script looks for types that end with
Responseand work backwards from there. This is to prevent creating commands for every struct type defined there, and only the ones that are actually commands. It also skips any types ending withFaultResponse, as there typically are noFaultcommands, only responses.
For the respective web service the command belongs to, add the command and response struct definitions
into <web-service-name>/types.go, and then run:
python3 python/gen_commands.py
Note: You can also typically run the generator within your IDE thanks to the
//go:generatelines towards the top of thetypes.gofiles.
Higher-level helpers
Some web service directories ship hand-written, higher-level helpers
built on top of the wire-layer commands. These are normal Go packages
— not covered by the gen_commands.py workflow above and not
expected to be regenerated.
- event/stream — channel-based event consumer that
owns the pull-point subscription lifecycle (Create, Pull, Renew,
Unsubscribe, reconnect with jittered backoff) and decodes
notifications into normalized typed Events. Vendor topic strings
(AXIS, Hikvision, Avigilon, Hanwha, Bosch, Dahua) are classified
into a small set of
Kindvalues. See the packagedoc.gofor the public surface and usage. - event/topic — topic identifier helpers.
When adding a similar higher-level helper, place it under the relevant web service directory as a sub-package so consumers find it next to the wire-layer types it builds on.