Update documentation with info on multithread protection.

[radsecproxy.git] / lib / include / radsec / radsec.h

diff --git a/lib/include/radsec/radsec.h b/lib/include/radsec/radsec.h
index 00c8d7b..1d718a0 100644 (file)
--- a/lib/include/radsec/radsec.h
+++ b/lib/include/radsec/radsec.h
@@ -1,7 +1,8 @@
 /** \file radsec.h
     \brief Public interface for libradsec.  */
 
-/* See LICENSE for licensing information.  */
+/* Copyright 2010-2013 NORDUnet A/S. All rights reserved.
+   See LICENSE for licensing information. */
 
 #ifndef _RADSEC_RADSEC_H_
 #define _RADSEC_RADSEC_H_ 1
@@ -67,6 +68,7 @@ enum rs_error_code {
     RSE_VENDOR_UNKNOWN = 42,
     RSE_CRED = 43,
     RSE_CERT = 44,
+    RSE_MAX = RSE_CERT
 };
 
 enum rs_conn_type {
@@ -166,10 +168,15 @@ typedef const struct value_pair rs_const_avp;
     that the context must not be freed before all other libradsec
     objects have been freed.
 
+    If support for POSIX threads was detected at configure and build
+    time \a rs_context_create will use mutexes to protect multiple
+    threads from stomping on each other in OpenSSL.
+
     \a ctx Address of pointer to a struct rs_context.  This is the
     output of this function.
 
-    \return RSE_OK (0) on success or RSE_NOMEM on out of memory.  */
+    \return RSE_OK (0) on success, RSE_SSLERR on TLS library
+    initialisation error and RSE_NOMEM on out of memory.  */
 int rs_context_create(struct rs_context **ctx);
 
 /** Free a context.  Note that the context must not be freed before
@@ -320,7 +327,17 @@ int rs_packet_create_authn_request(struct rs_connection *conn,
                                   const char *user_name,
                                   const char *user_pw);
 
-/*** Append \a tail to packet \a pkt.  */
+/** Add a new attribute-value pair to \a pkt. */
+int rs_packet_add_avp(struct rs_packet *pkt,
+                      unsigned int attr, unsigned int vendor,
+                      const void *data, size_t data_len);
+
+/** Append a new attribute to packet \a pkt. Note that this function
+    encodes the attribute and therefore might require the secret
+    shared with the thought recipient to be set in pkt->rpkt. Note
+    also that this function marks \a pkt as already encoded and can
+    not be used on packets with non-encoded value-pairs already
+    added. */
 int
 rs_packet_append_avp(struct rs_packet *pkt,
                     unsigned int attribute, unsigned int vendor,