Startsida Utforska Hjälp
Registrera dig Logga in
Apq
/
winscp
spegling av https://github.com/winscp/winscp.git
1
0
Fork 0
Filer Ärenden 0 Wiki
Gren: thirdparty_dev
Grenar Taggar
winscp
/
libs
/
neon
/
doc
/
html
/
refneon.html

refneon.html 12 KB
Permalänk Historik Rå

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113 
  1. <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>neon</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="ref.html" title="neon API reference"><link rel="prev" href="ref.html" title="neon API reference"><link rel="next" href="refconfig.html" title="neon-config"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">neon</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref.html">Prev</a> </td><th width="60%" align="center">neon API reference</th><td width="20%" align="right"> <a accesskey="n" href="refconfig.html">Next</a></td></tr></table><hr></div><div class="refentry"><a name="refneon"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>neon — HTTP and WebDAV client library</p></div><div class="refsect1"><a name="id1682"></a><h2>Description</h2><p>neon is an HTTP and WebDAV client library.  The major
    2. 

  2.     abstractions exposed are the HTTP <span class="emphasis"><em>session</em></span>,
    3. 

  3.     created by <a class="xref" href="refsess.html#ne_session_create">ne_session_create</a>; and the HTTP
    4. 

  4.     <span class="emphasis"><em>request</em></span>, created by <a class="xref" href="refreq.html#ne_request_create">ne_request_create</a>.  HTTP authentication is handled
    5. 

  5.     transparently for server and proxy servers, see <a class="xref" href="refauth.html#ne_set_server_auth">ne_set_server_auth</a>; complete SSL/TLS support is also
    6. 

  6.     included, see <a class="xref" href="refsslvfy.html#ne_ssl_set_verify">ne_ssl_set_verify</a>.</p></div><div class="refsect1"><a name="id1691"></a><h2>Conventions</h2><p>Some conventions are used throughout the neon API, to
    7. 

  7.     provide a consistent and simple interface; these are documented
    8. 

  8.     below.</p><div class="refsect2"><a name="id1694"></a><h3>Thread-safeness and global initialization</h3><p>neon itself is implemented to be thread-safe (avoiding any
    9. 

  9.     use of global state), but relies on the operating system providing
    10. 

  10.     a thread-safe resolver interface.  Modern operating systems offer
    11. 

  11.     the thread-safe <code class="function">getaddrinfo</code> interface, which
    12. 

  12.     neon supports; some others implement
    13. 

  13.     <code class="function">gethostbyname</code> using thread-local
    14. 

  14.     storage.</p><p>To allow thread-safe use of SSL in the OpenSSL and GnuTLS
    15. 

  15.     libraries neon must be configured using the
    16. 

  16.     <code class="literal">--enable-threadsafe-ssl</code>; if this is done,
    17. 

  17.     locking callbacks will be registered by <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>; note that care must be exercised if
    18. 

  18.     neon is used in conjunction with another library which uses
    19. 

  19.     OpenSSL or GnuTLS.</p><p>Some platforms and libraries used by neon require global
    20. 

  20.     initialization before use; notably:
    21. 

  21. 

  22.     </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">The <code class="literal">SIGPIPE</code> signal
    23. 

  23.       disposition must be set to <span class="emphasis"><em>ignored</em></span> or
    24. 

  24.       otherwise handled to avoid process termination when writing to a
    25. 

  25.       socket which has been shutdown by the peer.</li><li class="listitem">OpenSSL and GnuTLS require global
    26. 

  26.       initialization to load shared lookup
    27. 

  27.       tables.</li><li class="listitem">The Win32 socket library requires
    28. 

  28.       initialization before use.</li></ul></div><p>
    29. 

  29. 

  30.     The <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a> function should be called
    31. 

  31.     before any other use of neon to perform any necessary
    32. 

  32.     initialization needed for the particular platform.  Applications
    33. 

  33.     wishing to perform all the necessary process-global initialization
    34. 

  34.     steps themselves may omit to call <a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>
    35. 

  35.     (and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>); neon neither checks whether
    36. 

  36.     these functions are called nor calls them itself.</p><p>For some applications and configurations it may be necessary
    37. 

  37.     to call <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a> to initialize the support
    38. 

  38.     for internationalization in neon.</p></div><div class="refsect2"><a name="id1717"></a><h3>Asynchronous signal safety</h3><p>No function in neon is defined to be <span class="quote">“<span class="quote">async-signal safe</span>”</span> -
    39. 

  39.     that is, no function is safe to call from a signal handler.  Any
    40. 

  40.     call into the neon library from a signal handler will have
    41. 

  41.     undefined behaviour - in other words, it may crash the
    42. 

  42.     process.</p></div><div class="refsect2"><a name="id1721"></a><h3>Functions using global state</h3><p>Any function in neon may modify the
    43. 

  43.     <code class="literal">errno</code> global variable as a side-effect.  Except
    44. 

  44.     where explicitly documented, the value of <code class="literal">errno</code>
    45. 

  45.     is unspecified after any neon function call.</p><p>Other than in the use of <code class="literal">errno</code>, the only
    46. 

  46.     functions which use or modify process-global state in neon are
    47. 

  47.     as follows:
    48. 

  48. 

  49.     </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="xref" href="refsockinit.html#ne_sock_init">ne_sock_init</a>, <a class="xref" href="refi18n.html#ne_i18n_init">ne_i18n_init</a>, and <a class="xref" href="refsockinit.html#ne_sock_exit">ne_sock_exit</a>, as
    50. 

  50.       described above</li><li class="listitem"><code class="function">ne_debug_init</code> and
    51. 

  51.       <code class="function">ne_debug</code>, if enabled at compile time; for
    52. 

  52.       debugging output</li><li class="listitem"><a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a> for
    53. 

  53.       installing a process-global callback to be invoked on
    54. 

  54.       <code class="function">malloc</code> failure</li></ul></div></div><div class="refsect2"><a name="id1742"></a><h3>Namespaces</h3><p>To avoid possible collisions between names used for symbols
    55. 

  55.     and preprocessor macros by an application and the libraries it
    56. 

  56.     uses, it is good practice for each library to reserve a particular
    57. 

  57.     <span class="emphasis"><em>namespace prefix</em></span>.  An application which
    58. 

  58.     ensures it uses no names with these prefixes is then guaranteed to
    59. 

  59.     avoid such collisions.</p><p>The neon library reserves the use of the namespace
    60. 

  60.     prefixes <code class="literal">ne_</code> and <code class="literal">NE_</code>.  The
    61. 

  61.     libraries used by neon may also reserve certain namespaces;
    62. 

  62.     collisions between these libraries and a neon-based application
    63. 

  63.     will not be detected at compile time, since the underlying library
    64. 

  64.     interfaces are not exposed through the neon header files.  Such
    65. 

  65.     collisions can only be detected at link time, when the linker
    66. 

  66.     attempts to resolve symbols.  The following list documents some of
    67. 

  67.     the namespaces claimed by libraries used by neon; this list may
    68. 

  68.     be incomplete.</p><div class="variablelist"><table border="0" class="variablelist"><colgroup><col align="left" valign="top"><col></colgroup><tbody><tr><td><p><span class="term">SSL, ssl, TLS, tls, ERR_, BIO_, d2i_, i2d_, ASN1_</span></p></td><td>Some of the many prefixes used by the OpenSSL
    69. 

  69. 	library; little attempt has been made to keep exported symbols
    70. 

  70. 	within any particular prefixes for this
    71. 

  71. 	library.</td></tr><tr><td><p><span class="term">gnutls_, gcry_, gpg_</span></p></td><td>Namespaces used by the GnuTLS library (and
    72. 

  72.         dependencies thereof)</td></tr><tr><td><p><span class="term">XML_, Xml[A-Z]</span></p></td><td>Namespaces
    73. 

  73. 	used by the expat library.</td></tr><tr><td><p><span class="term">xml[A-Z], html[A-Z], docb[A-Z]</span></p></td><td>Namespaces used by the libxml2 library; a
    74. 

  74. 	relatively small number of symbols are used without these
    75. 

  75. 	prefixes.</td></tr><tr><td><p><span class="term">inflate, deflate, crc32, compress, uncompress, adler32,
    76. 

  76.         zlib</span></p></td><td>Namespaces used by the zlib library; a
    77. 

  77. 	relatively small number of symbols are used without these
    78. 

  78. 	prefixes.</td></tr><tr><td><p><span class="term">krb5, gss, GSS, asn1, decode_krb5, encode_krb5, profile,
    79. 

  79.         mit</span></p></td><td>Some of the prefixes used by the MIT GSSAPI
    80. 

  80.         library and dependencies thereof; a number of symbols lie
    81. 

  81.         outside these prefixes.</td></tr><tr><td><p><span class="term">pakchois_</span></p></td><td>Namespace used by the pakchois 
    82. 

  82.          library.</td></tr><tr><td><p><span class="term">px_</span></p></td><td>Namespace used by the libproxy
    83. 

  83.          library.</td></tr></tbody></table></div></div><div class="refsect2"><a name="id1782"></a><h3>Argument validation</h3><p>neon does not attempt to validate that the parameters
    84. 

  84.     passed to functions conform to the API (for instance, checking
    85. 

  85.     that pointer arguments are not <code class="literal">NULL</code>).  Any use of the neon API
    86. 

  86.     which is not documented to produce a certain behaviour results is
    87. 

  87.     said to produce <span class="emphasis"><em>undefined behaviour</em></span>; it is
    88. 

  88.     likely that neon will segfault under these conditions.</p></div><div class="refsect2"><a name="id1787"></a><h3>URI paths, WebDAV metadata</h3><p>The path strings passed to any function must be
    89. 

  89.     <span class="emphasis"><em>URI-encoded</em></span> by the application; neon never
    90. 

  90.     performs any URI encoding or decoding internally.  WebDAV property
    91. 

  91.     names and values must be valid UTF-8 encoded Unicode
    92. 

  92.     strings.</p></div><div class="refsect2"><a name="id1791"></a><h3>User interaction</h3><p>As a pure library interface, neon will never produce
    93. 

  93.     output on <code class="constant">stdout</code> or
    94. 

  94.     <code class="constant">stderr</code>; all user interaction is the
    95. 

  95.     responsibility of the application.</p></div><div class="refsect2"><a name="id1796"></a><h3>Memory handling</h3><p>neon does not attempt to cope gracefully with an
    96. 

  96.     out-of-memory situation; instead, by default, the
    97. 

  97.     <code class="function">abort</code> function is called to immediately
    98. 

  98.     terminate the process.  An application may register a custom
    99. 

  99.     function which will be called before <code class="function">abort</code> in
    100. 

  100.     such a situation; see <a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a>.</p></div><div class="refsect2"><a name="id1802"></a><h3>Callbacks and userdata</h3><p>Whenever a callback is registered, a
    101. 

  101.     <code class="literal">userdata</code> pointer is also used to allow the
    102. 

  102.     application to associate a context with the callback.  The
    103. 

  103.     userdata is of type <em class="type">void *</em>, allowing any pointer to
    104. 

  104.     be used.</p></div><div class="refsect2"><a name="id1807"></a><h3>Large File Support</h3><p>Since version 0.27.0, neon transparently uses the "LFS
    105. 

  105.     transitional" interfaces in functions which use file descriptors.
    106. 

  106.     This allows use of files larger than 2GiB on platforms with a
    107. 

  107.     native 32-bit <code class="literal">off_t</code> type, where LFS support is
    108. 

  108.     available.</p><p>Some neon interfaces use the <code class="literal">ne_off_t</code>
    109. 

  109.     type, which is defined to be either <code class="literal">off_t</code> or
    110. 

  110.     <code class="literal">off64_t</code> according to whether LFS support is
    111. 

  111.     detected at build time.  neon does not use or require the
    112. 

  112.     <code class="literal">-D_FILE_OFFSET_BITS=64</code> macro definition.</p></div></div><div class="refsect1"><a name="id1816"></a><h2>See also</h2><p><a class="xref" href="refsess.html" title="ne_session_create"><span class="refentrytitle">ne_session_create</span></a>, <a class="xref" href="refalloc.html#ne_oom_callback">ne_oom_callback</a>,
    113. 

  113.     <a class="ulink" href="https://notroj.github.io/neon/" target="_top">https://notroj.github.io/neon/</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="refconfig.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">neon API reference </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> neon-config</td></tr></table></div></body></html>
    114.