packages icon



 NEON(3)                         neon 0.30.2                         NEON(3)
 neon API reference                                       neon API reference

                              30 September 2016



 NAME
      neon - HTTP and WebDAV client library

 DESCRIPTION
      neon is an HTTP and WebDAV client library. The major abstractions
      exposed are the HTTP session, created by ne_session_create; and the
      HTTP request, created by ne_request_create. HTTP authentication is
      handled transparently for server and proxy servers, see
      ne_set_server_auth; complete SSL/TLS support is also included, see
      ne_ssl_set_verify.

 CONVENTIONS
      Some conventions are used throughout the neon API, to provide a
      consistent and simple interface; these are documented below.

    Thread-safeness and global initialization
      neon itself is implemented to be thread-safe (avoiding any use of
      global state), but relies on the operating system providing a
      thread-safe resolver interface. Modern operating systems offer the
      thread-safe getaddrinfo interface, which neon supports; some others
      implement gethostbyname using thread-local storage.

      To allow thread-safe use of SSL in the OpenSSL and GnuTLS libraries
      neon must be configured using the --enable-threadsafe-ssl; if this is
      done, locking callbacks will be registered by ne_sock_init; note that
      care must be exercised if neon is used in conjunction with another
      library which uses OpenSSL or GnuTLS.

      Some platforms and libraries used by neon require global
      initialization before use; notably:

      +   The SIGPIPE signal disposition must be set to ignored or otherwise
          handled to avoid process termination when writing to a socket
          which has been shutdown by the peer.

      +   OpenSSL and GnuTLS require global initialization to load shared
          lookup tables.

      +   The Win32 socket library requires initialization before use.

      The ne_sock_init function should be called before any other use of
      neon to perform any necessary initialization needed for the particular
      platform. Applications wishing to perform all the necessary
      process-global initialization steps themselves may omit to call
      ne_sock_init (and ne_sock_exit); neon neither checks whether these
      functions are called nor calls them itself.

      For some applications and configurations it may be necessary to call
      ne_i18n_init to initialize the support for internationalization in



                                    - 1 -       Formatted:  December 7, 2024






 NEON(3)                         neon 0.30.2                         NEON(3)
 neon API reference                                       neon API reference

                              30 September 2016



      neon.

    Asynchronous signal safety
      No function in neon is defined to be async-signal safe - that is, no
      function is safe to call from a signal handler. Any call into the neon
      library from a signal handler will have undefined behaviour - in other
      words, it may crash the process.

    Functions using global state
      Any function in neon may modify the errno global variable as a
      side-effect. Except where explicitly documented, the value of errno is
      unspecified after any neon function call.

      Other than in the use of errno, the only functions which use or modify
      process-global state in neon are as follows:

      +   ne_sock_init, ne_i18n_init, and ne_sock_exit, as described above

      +   ne_debug_init and ne_debug, if enabled at compile time; for
          debugging output

      +   ne_oom_callback for installing a process-global callback to be
          invoked on malloc failure

    Namespaces
      To avoid possible collisions between names used for symbols and
      preprocessor macros by an application and the libraries it uses, it is
      good practice for each library to reserve a particular namespace
      prefix. An application which ensures it uses no names with these
      prefixes is then guaranteed to avoid such collisions.

      The neon library reserves the use of the namespace prefixes ne_ and
      NE_. The libraries used by neon may also reserve certain namespaces;
      collisions between these libraries and a neon-based application will
      not be detected at compile time, since the underlying library
      interfaces are not exposed through the neon header files. Such
      collisions can only be detected at link time, when the linker attempts
      to resolve symbols. The following list documents some of the
      namespaces claimed by libraries used by neon; this list may be
      incomplete.

      SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_
          Some of the many prefixes used by the OpenSSL library; little
          attempt has been made to keep exported symbols within any
          particular prefixes for this library.

      gnutls_, gcry_, gpg_
          Namespaces used by the GnuTLS library (and dependencies thereof)




                                    - 2 -       Formatted:  December 7, 2024






 NEON(3)                         neon 0.30.2                         NEON(3)
 neon API reference                                       neon API reference

                              30 September 2016



      XML_, Xml[A-Z]
          Namespaces used by the expat library.

      xml[A-Z], html[A-Z], docb[A-Z]
          Namespaces used by the libxml2 library; a relatively small number
          of symbols are used without these prefixes.

      inflate, deflate, crc32, compress, uncompres, adler32, zlib
          Namespaces used by the zlib library; a relatively small number of
          symbols are used without these prefixes.

      krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile, mit
          Some of the prefixes used by the MIT GSSAPI library and
          dependencies thereof; a number of symbols lie outside these
          prefixes.

      pakchois_
          Namespace used by the pakchois library.

      px_
          Namespace used by the libproxy library.

    Argument validation
      neon does not attempt to validate that the parameters passed to
      functions conform to the API (for instance, checking that pointer
      arguments are not NULL). Any use of the neon API which is not
      documented to produce a certain behaviour results is said to produce
      undefined behaviour; it is likely that neon will segfault under these
      conditions.

    URI paths, WebDAV metadata
      The path strings passed to any function must be URI-encoded by the
      application; neon never performs any URI encoding or decoding
      internally. WebDAV property names and values must be valid UTF-8
      encoded Unicode strings.

    User interaction
      As a pure library interface, neon will never produce output on stdout
      or stderr; all user interaction is the responsibilty of the
      application.

    Memory handling
      neon does not attempt to cope gracefully with an out-of-memory
      situation; instead, by default, the abort function is called to
      immediately terminate the process. An application may register a
      custom function which will be called before abort in such a situation;
      see ne_oom_callback.

    Callbacks and userdata



                                    - 3 -       Formatted:  December 7, 2024






 NEON(3)                         neon 0.30.2                         NEON(3)
 neon API reference                                       neon API reference

                              30 September 2016



      Whenever a callback is registered, a userdata pointer is also used to
      allow the application to associate a context with the callback. The
      userdata is of type void *, allowing any pointer to be used.

    Large File Support
      Since version 0.27.0, neon transparently uses the "LFS transitional"
      interfaces in functions which use file descriptors. This allows use of
      files larger than 2GiB on platforms with a native 32-bit off_t type,
      where LFS support is available.

      Some neon interfaces use the ne_off_t type, which is defined to be
      either off_t or off64_t according to whether LFS support is detected
      at build time. neon does not use or require the -D_FILE_OFFSET_BITS=64
      macro definition.

 SEE ALSO
      ne_session_create(3), ne_oom_callback

 AUTHOR
      Joe Orton <neon@lists.manyfish.co.uk>
          Author.

 COPYRIGHT


























                                    - 4 -       Formatted:  December 7, 2024