- added API documentation for RSession (LIB61850-360)

src/goose/goose_publisher.h

@@ -54,6 +54,8 @@ typedef struct sGoosePublisher* GoosePublisher;
  *
  * \param parameters GOOSE communication parameters
  * \param interfaceId name of the Ethernet interface to use (e.g. "eth0")
+ * 
+ * \return the new GoosePublisher instance
  */
 LIB61850_API GoosePublisher
 GoosePublisher_create(CommParameters* parameters, const char* interfaceID);
@@ -64,6 +66,8 @@ GoosePublisher_create(CommParameters* parameters, const char* interfaceID);
  * \param parameters GOOSE communication parameters
  * \param interfaceId name of the Ethernet interface to use (e.g. "eth0")
  * \param useVlanTag enable or disable the usage of VLAN tags in GOOSE messages
+ * 
+ * \return the new GoosePublisher instance
  */
 LIB61850_API GoosePublisher
 GoosePublisher_createEx(CommParameters* parameters, const char* interfaceID, bool useVlanTag);
@@ -73,6 +77,8 @@ GoosePublisher_createEx(CommParameters* parameters, const char* interfaceID, boo
  *
  * \param session R-session protocol instance to use
  * \param appId the appID value to use
+ * 
+ * \return the new GoosePublisher instance
  */
 LIB61850_API GoosePublisher
 GoosePublisher_createRemote(RSession session, uint16_t appId);

src/r_session/r_session.c

@@ -163,7 +163,7 @@ RSession_create()
     return NULL;
 }
 
-/* Required only for version 1 of the protocol! */
+/* only for version 1 of the protocol! */
 RSessionError
 RSession_setSecurity(RSession self, RSecurityAlgorithm secAlgo, RSignatureAlgorithm sigAlgo)
 {
@@ -1074,6 +1074,8 @@ getKeyById(RSession self, uint32_t keyId)
 RSessionError
 RSession_removeKey(RSession self, uint32_t keyId)
 {
+    RSessionError retVal = R_SESSION_ERROR_OK;
+
     Semaphore_wait(self->keyListLock);
 
     RSessionKeyMaterial keyMaterial = getKeyById(self, keyId);
@@ -1083,6 +1085,9 @@ RSession_removeKey(RSession self, uint32_t keyId)
 
         RSessionKeyMaterial_destroy(keyMaterial);
     }
+    else {
+        retVal = R_SESSION_ERROR_INVALID_KEY;
+    }
 
     Semaphore_post(self->keyListLock);
 
@@ -1091,7 +1096,21 @@ RSession_removeKey(RSession self, uint32_t keyId)
         self->currentKeyId = 0;
     }
 
-    return R_SESSION_ERROR_OK;
+    return retVal;
+}
+
+void
+RSession_removeAllKeys(RSession self)
+{
+    Semaphore_wait(self->keyListLock);
+
+    LinkedList_destroyDeep(self->keyList, (LinkedListValueDeleteFunction)RSessionKeyMaterial_destroy);
+
+    self->keyList = LinkedList_create();
+
+    self->currentKeyId = 0;
+
+    Semaphore_post(self->keyListLock);
 }
 
 /**

src/r_session/r_session.h

@@ -1,7 +1,7 @@
 /*
  *  r_session.h
  *
- *  Copyright 2013-2021 Michael Zillgith
+ *  Copyright 2013-2022 Michael Zillgith
  *
  *  This file is part of libIEC61850.
  *
@@ -21,8 +21,8 @@
  *  See COPYING file for the complete license text.
  */
 
-#ifndef LIBIEC61850_SRC_SAMPLED_VALUES_R_SESSION_H_
+#ifndef LIBIEC61850_R_SESSION_H_
-#define LIBIEC61850_SRC_SAMPLED_VALUES_R_SESSION_H_
+#define LIBIEC61850_R_SESSION_H_
 
 #include "libiec61850_common_api.h"
 #include "hal_socket.h"
@@ -91,10 +91,26 @@ RSession_create();
 LIB61850_API void
 RSession_setBufferSize(RSession self, uint16_t bufferSize);
 
-/* Required only for version 1 of the protocol! */
+/**
+ * \brief Set the security algorithms for the session instance
+ * 
+ * \note only for version 1 of the protocol!
+ * 
+ * \param secAlgo encryption algorithm to be used for the session instance
+ * \param sigAlgo signature algorithm to be used for the session instance
+ * 
+ * \return returns R_SESSION_ERROR_OK
+ */
 LIB61850_API RSessionError
 RSession_setSecurity(RSession self, RSecurityAlgorithm secAlgo, RSignatureAlgorithm sigAlgo);
 
+/**
+ * \brief Bind the RSession instance to a specific local IP address and UDP port
+ * 
+ * \param self the RSession instance
+ * \param localAddress the local IP address to use
+ * \param localPort the local UDP port to use (default is 102)
+*/
 LIB61850_API RSessionError
 RSession_setLocalAddress(RSession self, const char* localAddress, int localPort);
 
@@ -165,9 +181,23 @@ RSession_stopListening(RSession self);
 LIB61850_API RSessionError
 RSession_addKey(RSession self, uint32_t keyId, uint8_t* key, int keyLength, RSecurityAlgorithm secAlgo, RSignatureAlgorithm sigAlgo);
 
+/**
+ * \brief Remove key from the list of accepted keys
+ * 
+ * \param self the RSession instance
+ * \param keyId the key ID is unique for the security association
+ */
 LIB61850_API RSessionError
 RSession_removeKey(RSession self, uint32_t keyId);
 
+/**
+ * \brief Remove all keys from the list of accepted keys
+ * 
+ * \param self the RSession instance 
+ */
+void
+RSession_removeAllKeys(RSession self);
+
 typedef enum
 {
     RSESSION_KEY_EVENT__NEED_KEY = 1
@@ -179,6 +209,10 @@ typedef void (*RSession_KeyEventHandler) (void* parameter, RSession rSession, RS
  * \brief Set a callback handler to receive key events from the RSession instance
  *
  * e.g. when the RSession instance has no valid key for the received messages or to publish messages.
+ * 
+ * \param self the RSession instance
+ * \param handler the callback that is called when a new event happens
+ * \param parameter user provided parameter that is passed to the user callback
  */
 LIB61850_API void
 RSession_setKeyEventHandler(RSession self, RSession_KeyEventHandler handler, void* parameter);
@@ -188,6 +222,8 @@ RSession_setKeyEventHandler(RSession self, RSession_KeyEventHandler handler, voi
  *
  * \param self the RSession instance
  * \param keyId the key ID of the new active key (has to be added with \ref RSession_addKey before).
+ * 
+ * \return R_SESSION_ERROR_INVALID_KEY when no valid key with the given keyId is avialable, R_SESSION_ERROR_OK otherwise
  */
 LIB61850_API RSessionError
 RSession_setActiveKey(RSession self, uint32_t keyId);
@@ -204,4 +240,4 @@ RSession_destroy(RSession self);
 }
 #endif
 
-#endif /* LIBIEC61850_SRC_SAMPLED_VALUES_R_SESSION_H_ */
+#endif /* LIBIEC61850_R_SESSION_H_ */

src/sampled_values/sv_publisher.h

@@ -91,6 +91,14 @@ SVPublisher_create(CommParameters* parameters, const char* interfaceId);
 LIB61850_API SVPublisher
 SVPublisher_createEx(CommParameters* parameters, const char* interfaceId, bool useVlanTag);
 
+/**
+ * \brief Create a new SVPublisher instance for R-SMV
+ *
+ * \param session R-session protocol instance to use
+ * \param appId the appID value to use
+ * 
+ * \return the new SVPublisher instance
+ */
 LIB61850_API SVPublisher
 SVPublisher_createRemote(RSession session, uint16_t appId);