userapps/opensource/net-snmp/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