Move example agent into new subdir examples/
Rename example agent to simple agent

We're going to have other example agents in the examples/ subdirectory as
well, therefore the name "example agent" would be ambiguous. The MIB and its
contents have been renamed, too.
Non-functional improvements to the simple agent

simple_agent.py's heading comment block:
- Add note on running the run_simple_agent.sh script
- Add note on using sudo when starting the agent directly
- Encourage user to use own <rosecret> instead of "public"

simple_agent.py's counters code:
- Prettify sort order of code blocks
- Explain initialization value
- Document that increment() is a counter object's method more explicitly

run_simple_agent.sh:
- Mention snmpget as well
New example threading_agent.py demonstrating asynchronous data updates

The default simple_agent.py always blocked until certain events occured, eg.
SNMP requests had to be processed, and only updated its SNMP objects
inbetween. Also SNMP requests couldn't be handled while data was in the
process of being updated. Thus here's a more real life-usable example that
outsources data updating into a separate thread. It does however not address
possible locking issues.
Small update to the README

- Phrase missing API stability less dramatically
- Add TODO of SNMP notifications/traps
Fix overseen references to "example" that should be "simple"

Thanks to mjs7231 for reporting.
simple_agent.py: Remove the caret that shouldn't be

Narf...
Fix more overseen references to "example" in run_simple_agent.sh
Use local copy of netsnmpagent module for example agents

So you don't have to "make install" first.
Undo part of fa6e2d9723 (much longer string in simple_agent.py)

That line was intended for debugging only.
Adapt the Makefile's srcdist and rpms targets to the new examples dir
Explicitly comment why we set watcher_info struct's max_size manually
Add missing netsnmp_watcher_info fields definition to netsnmpapi

Basically we do not need fields definitions for net-snmp structures
that we never modify ourselves. However in this case we actually
tried setting netsnmp_watcher_info's "max_size" field which resulted
in a no-op.

Reported by Max "mk23" Kalika <max.kalika+projects@gmail.com>.
Deref watcher before trying to its max_size property

The netsnmp_watcher_info structure returned by netsnmp_create_watcher_info is
a pointer, so it must be de-referenced with ctypes' "contents" attribute
before any of its properties can be set.

Reported by Max "mk23" Kalika <max.kalika+projects@gmail.com>.
Fix comment added in 60d51c93
Use WATCHER_MAX_SIZE instead of WATCHER_SIZE_STRLEN for 5.4.x compatibility

We used to rely on net-snmp >= 5.5 behavior by setting a WATCHER_SIZE_STRLEN
flag that didn't exist in net-snmp 5.4.x yet. For backwards compatibility we
now use WATCHER_MAX_SIZE and update the used netsnmp_watcher_info structure's
"data_size" field ourselves.

Reported by Max "mk23" Kalika <max.kalika+projects@gmail.com>.
Update README with net-snmp compatibility remarks
Update README with new credits
Move documentation on examples into own README in the examples directory

To put the information closer to where you would be looking for it.
Advertise support for alternative AgentX transports more explicitly

We did already support alternative transports for the AgentX communication
between subagents and master snmpd instances, that is, not just UNIX domain
sockets but eg. also TCP ports. These are specified through transport
specifications that follow the format described in the "LISTENING ADDRESSES"
section in the snmpd(8) manpage.

This change modifies wording that would suggest we supported alternative
UNIX domain socket paths only. It also adds a new script to run simple_agent.py
against a snmpd instance over a TCP port, surprisingly named
"run_simple_agent_over_tcpsocket.sh".