API Chnage: Updated session to be dynamically allocated, so session creation... (39546c1a) · Commits · kinetic-archive / kinetic-c

Makefile

+2 −2

Original line number	Diff line number	Diff line
		@@ -143,7 +143,7 @@ $(OUT_DIR)/%.o: ${LIB_DIR}/bus/%.c ${LIB_DIR}/bus/%.h
		${OUT_DIR}/*.o: src/lib/kinetic_types_internal.h


		ci: uninstall all stop_simulator test_internals install
		ci: uninstall stop_simulator start_simulator all stop_simulator install uninstall
		@echo
		@echo --------------------------------------------------------------------------------
		@echo $(PROJECT) build completed successfully!
		@@ -407,7 +407,7 @@ run: $(UTIL_EXEC)
		@echo Running test utility: $(UTIL_EXEC)
		@echo --------------------------------------------------------------------------------
		@echo
		$(UTIL_EXEC) instanterase
		# $(UTIL_EXEC) instanterase
		$(UTIL_EXEC) noop
		exec $(UTIL_EXEC) put get delete
		@echo

config/Doxyfile

+1 −1

Original line number	Diff line number	Diff line
		@@ -38,7 +38,7 @@ PROJECT_NAME = kinetic-c
		# could be handy for archiving the generated documentation or if some version
		# control system is used.

		PROJECT_NUMBER = "v0.10.1"
		PROJECT_NUMBER = "v0.11.0"

		# Using the PROJECT_BRIEF tag one can provide an optional one line description
		# for a project that appears at the top of each page and should give viewer a

config/VERSION

+1 −1

Original line number	Diff line number	Diff line
		0.10.1
		0.11.0

include/kinetic_admin_client.h

+50 −33

Original line number	Diff line number	Diff line
		@@ -31,7 +31,7 @@
		* @param log_level Logging level (-1:none, 0:error, 1:info, 2:verbose, 3:full)
		*
		* @return Returns a pointer to a `KineticClient`. You need to pass
		* this pointer to KineticClient_CreateConnection() to create
		* this pointer to KineticClient_CreateSession() to create
		* new connections.
		* Once you are finished will the `KineticClient`, and there
		* are no active connections. The pointer should be release
		@@ -45,95 +45,112 @@ KineticClient * KineticAdminClient_Init(const char* log_file, int log_level);
		void KineticAdminClient_Shutdown(KineticClient * const client);

		/**
		* @brief Initializes the Kinetic API, configures logging destination, establishes a
		* connection to the specified Kinetic Device, and establishes a session.
		* @brief Creates a session with the Kinetic Device per specified configuration.
		*
		* @param session Configured KineticSession to connect
		* .config `KineticSessionConfig` structure which must be configured
		* @param config `KineticSessionConfig` structure which must be configured
		* by the client prior to creating the device connection.
		* .host Host name or IP address to connect to
		* .port Port to establish socket connection on
		* .clusterVersion Cluster version to use for the session
		* .identity Identity to use for the session
		* .hmacKey Key to use for HMAC calculations (NULL-terminated string)
		* .connection Pointer to dynamically allocated connection which will be
		* populated upon establishment of a connection.
		*
		* @return Returns the resulting `KineticStatus`, and `session->connection`
		* will be populated with a session instance pointer upon success.
		* The client should call KineticAdminClient_DestroyConnection() in
		* order to shutdown a connection and cleanup resources when
		* done using a KineticSession.
		* .pin PIN to use for PIN-based operations
		* @param client The `KineticClient` pointer returned from KineticClient_Init()
		* @param session Pointer to a KineticSession pointer that will be populated
		* with the allocated/created session upon success.
		*
		* @return Returns the resulting `KineticStatus`, and `session`
		* will be populated with a pointer to the session instance
		* upon success. The client should call
		* KineticClient_DestroySession() in order to shutdown a
		* connection and cleanup resources when done using a
		* `KineticSession`.
		*/
		KineticStatus KineticAdminClient_CreateConnection(KineticSession * const session,
		KineticClient * const client);
		KineticStatus KineticAdminClient_CreateSession(KineticSessionConfig * const config,
		KineticClient * const client, KineticSession** session);

		/**
		* @brief Closes the connection to a host.
		*
		* @param session The connected `KineticSession` to close. The connection
		* @param session The connected `KineticSession` to close. The session
		* instance will be freed by this call after closing the
		* connection.
		* connection, so the pointer should not longer be used.
		*
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticAdminClient_DestroyConnection(KineticSession * const session);
		KineticStatus KineticAdminClient_DestroySession(KineticSession * const session);

		/**
		* @brief Sets the erase PIN of the Kinetic Device.
		*
		* @param pin New erase PIN to set.
		* @param session The connected `KineticSession` to close. The session
		* instance will be freed by this call after closing the
		* connection, so the pointer should not longer be used.
		* @param old_pin Old erase PIN to change.
		* @param new_pin New erase PIN to change to.
		*
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticAdminClient_SetErasePin(KineticSession const * const session,
		ByteArray pin);
		ByteArray old_pin, ByteArray new_pin);

		/**
		* @brief Executes a SecureErase command to erase all data from the Kinetic device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param pin PIN to send with operation, which must match the configured erase PIN.
		*
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticAdminClient_SecureErase(KineticSession const * const session);
		KineticStatus KineticAdminClient_SecureErase(KineticSession const * const session,
		ByteArray pin);

		/**
		* @brief Executes an InstantErase command to erase all data from the Kinetic device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param pin PIN to send with operation, which must match the configured erase PIN.
		*
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticAdminClient_InstantErase(KineticSession const * const session);
		KineticStatus KineticAdminClient_InstantErase(KineticSession const * const session,
		ByteArray pin);

		/**
		* @brief Sets the lock PIN of the Kinetic Device.
		*
		* @param pin New lock PIN to set.
		* @param session The connected `KineticSession` to close. The session
		* instance will be freed by this call after closing the
		* connection, so the pointer should not longer be used.
		* @param old_pin Old erase PIN to change.
		* @param new_pin New erase PIN to change to.
		*
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticAdminClient_SetLockPin(KineticSession const * const session,
		ByteArray pin);
		ByteArray old_pin, ByteArray new_pin);

		/**
		* @brief Executes a LOCK command to lock the Kinetic device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param pin PIN to send with operation, which must match the configured lock PIN.
		*
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticAdminClient_LockDevice(KineticSession const * const session);
		KineticStatus KineticAdminClient_LockDevice(KineticSession const * const session,
		ByteArray pin);

		/**
		* @brief Executes an UNLOCK command to unlock the Kinetic device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param pin PIN to send with operation, which must match the configured lock PIN.
		*
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticAdminClient_UnlockDevice(KineticSession const * const session);
		KineticStatus KineticAdminClient_UnlockDevice(KineticSession const * const session,
		ByteArray pin);

		/**
		* @brief Executes a GETLOG command to retrieve specific configuration and/or

include/kinetic_client.h

+26 −27

Original line number	Diff line number	Diff line
		@@ -30,7 +30,7 @@
		* @param log_level Logging level (-1:none, 0:error, 1:info, 2:verbose, 3:full)
		*
		* @return Returns a pointer to a `KineticClient`. You need to pass
		* this pointer to KineticClient_CreateConnection() to create
		* this pointer to KineticClient_CreateSession() to create
		* new connections.
		* Once you are finished will the `KineticClient`, and there
		* are no active connections. The pointer should be release
		@@ -47,11 +47,9 @@ KineticClient * KineticClient_Init(const char* log_file, int log_level);
		void KineticClient_Shutdown(KineticClient * const client);

		/**
		* @brief Initializes the Kinetic API, configures logging destination, establishes a
		* connection to the specified Kinetic Device, and establishes a session.
		* @brief Creates a session with the Kinetic Device per specified configuration.
		*
		* @param session Configured KineticSession to connect
		* .config `KineticSessionConfig` structure which must be configured
		* @param config `KineticSessionConfig` structure which must be configured
		* by the client prior to creating the device connection.
		* .host Host name or IP address to connect to
		* .port Port to establish socket connection on
		@@ -59,29 +57,30 @@ void KineticClient_Shutdown(KineticClient * const client);
		* .identity Identity to use for the session
		* .hmacKey Key to use for HMAC calculations (NULL-terminated string)
		* .pin PIN to use for PIN-based operations
		* .connection Pointer to dynamically allocated connection which will be
		* populated upon establishment of a connection.
		*
		* @param client The KineticClient pointer returned from KineticClient_Init()
		*
		* @return Returns the resulting `KineticStatus`, and `session->connection`
		* will be populated with a session instance pointer upon success.
		* The client should call KineticClient_DestroyConnection() in
		* order to shutdown a connection and cleanup resources when
		* done using a KineticSession.
		* @param client The `KineticClient` pointer returned from KineticClient_Init()
		* @param session Pointer to a KineticSession pointer that will be populated
		* with the allocated/created session upon success.
		*
		* @return Returns the resulting `KineticStatus`, and `session`
		* will be populated with a pointer to the session instance
		* upon success. The client should call
		* KineticClient_DestroySession() in order to shutdown a
		* connection and cleanup resources when done using a
		* `KineticSession`.
		*/
		KineticStatus KineticClient_CreateConnection(KineticSession * const session, KineticClient * const client);
		KineticStatus KineticClient_CreateSession(KineticSessionConfig * const config,
		KineticClient * const client, KineticSession** session);

		/**
		* @brief Closes the connection to a host.
		*
		* @param session The connected `KineticSession` to close. The connection
		* @param session The connected `KineticSession` to close. The session
		* instance will be freed by this call after closing the
		* connection.
		* connection, so the pointer should not longer be used.
		*
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticClient_DestroyConnection(KineticSession * const session);
		KineticStatus KineticClient_DestroySession(KineticSession * const session);

		/**
		* @brief Executes a NOOP command to test whether the Kinetic Device is operational.