← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/net-snmp/gutsy-security

« back to all changes in this revision

Viewing changes to include/net-snmp/library/README

  • Committer: Bazaar Package Importer
  • Author(s): Martin Pitt
  • Date: 2004-09-13 12:06:21 UTC
  • Revision ID: james.westby@ubuntu.com-20040913120621-g952ntonlleihcvm
Tags: upstream-5.1.1
Import upstream version 5.1.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/net-snmp/library/README
 
1
One of the goals of the Net-SNMP v5 development line, is to try and
 
2
clarify the distinction between the "public" library API, and routines
 
3
that are regarded as being more "internal" to the library.
 
4
 
 
5
  This doesn't mean that application writers are discouraged from
 
6
making use of such internal routines.  There is a strong feeling
 
7
within the development team that as much as possible of the library
 
8
should be made externally visible, to support writing as wide a
 
9
range of applications as possible.  To that end, most routines
 
10
will be declared within an installed header file, rather than
 
11
privately within the library code files themselves.
 
12
 
 
13
  The public/internal categorisation is rather concerned with issues
 
14
of documentation, stability, and ease of programming.  The public
 
15
API routines have been selected as those covering the more common
 
16
requirements (e.g. creating SNMP requests, sending them to other SNMP
 
17
agents, and interpreting the results), together with certain supporting
 
18
activities (e.g. run-time configuration).
 
19
 
 
20
  The intention is that these routines should be properly documented,
 
21
and remain relatively stable.  We will attempt to avoid changing the
 
22
profile of these interfaces, and would normally provide some mechanism
 
23
to retain backward compatability if need be.
 
24
 
 
25
  On the other hand, the internal API routines are regarded as just
 
26
that - "internal" - so may legitimately be changed without providing
 
27
any compatability mechanism.  You are perfectly free to make use of
 
28
these routines, but be aware that you do so "at your own risk".
 
29
 
 
30
[This statement is in no way intended to challenge or amend the status
 
31
 of the disclaimers in the top-level 'COPYING' file, which remain
 
32
 unchanged  as the legal basis for using this code]
 
33
 
 
34
 
 
35
  There are (currently) eight main "public API" header files, relating
 
36
to various areas of SNMP programming, plus a combined "all-in-one"
 
37
header file (net-snmp-includes.h).
 
38
  Currently these simply include the relevant library header files
 
39
following the UCD-SNMP organisation.  However, the intention is for
 
40
future releases to declare the public API calls directly within these
 
41
top-level header files, and use the 'library/*.h' files for the more
 
42
internal calls.  (i.e. those that are more likely to change over time).
 
43
 
 
44
  Until this process can be started, the best approximation to the
 
45
"public API" list is probably those routines that are documented
 
46
in manual pages.  Apologies for any confusion, but hopefully this
 
47
process will result in a clearer end result than at present.
 
48
 
 
49
Applications writers are encouraged to start #including the new header
 
50
files as soon as possible - either individually, or using the combined
 
51
wrapper file.  Hopefully, with only a handful of top-level files, it
 
52
will be reasonably clear which file(s) might be appropriate for any
 
53
particular programming requirement.
 
54
 
 
55
 
 
56
 
 
57
  One final disclaimer:  The above description represents my own
 
58
personal aims and understanding of the likely development of the
 
59
library API.  While I have every confidence in having the support of
 
60
the other developers (or being able to persuade them of the benefits
 
61
of this approach!), it may turn out that things actually take a different
 
62
route.  Anyone wishing to influence the organisation of the eventual
 
63
library API is encouraged to subscribe to the net-snmp-coders mailing
 
64
list, and contribute to the discussions there.
 
65
 
 
66
Dave Shield
 
67
February 2002