Added KineticAdminClient_GetDeviceSpecificLog to retrieve device-specific log info by name/key. (b304bc01) · Commits · kinetic-archive / kinetic-c

RELEASE.md

+2 −1

Original line number	Diff line number	Diff line
		@@ -6,7 +6,7 @@ v0.12.0 (kinetic-protocol 3.0.5)
		* Added new `KineticAdminClient` API (see `include/kinetic_admin_client.h`)
		* Reloacted existing admin methods to admin API
		* `KineticClient_InstantSecureErase` => `KineticAdminClient_InstantErase`/`KineticAdminClient_SecureErase`
		* `KineticClient_GetLog` => `KineticAdminClient_GetLog`
		* `KineticClient_GetLog` => `KineticAdminClient_GetLog`/`KineticAdminClient_GetDeviceSpecificLog`
		* `KineticClient_FreeDeviceInfo` => `KineticAdminClient_LogInfo`
		* Updated `kinetic-c-util` to support new Admin API. Still need to add support for printing info returned from `KineticAdminClient_GetLog`
		* Changed `kinetic-c-util` API to use `getopt_long` for operations in addition to parameters and added usage info via `--help`/`-?` option.
		@@ -22,6 +22,7 @@ v0.12.0 (kinetic-protocol 3.0.5)
		* `KINETIC_STATUS_ACL_ERROR`
		* `KINETIC_STATUS_NOT_AUTHORIZED`
		* `KINETIC_STATUS_INVALID_FILE`
		* `KINETIC_STATUS_INVALID_LOG_TYPE`
		* Set larger timeouts for operations that tend to take approx. 10 seconds, to prevent non-deterministic failures.
		* API change: Eliminated KineticClientConfig.writerThreads, since sender threads are gone.

include/kinetic_admin_client.h

+41 −22

Original line number	Diff line number	Diff line
		@@ -29,10 +29,10 @@
		*
		* @param config A configuration struct.
		*
		* @return Returns a pointer to a `KineticClient`. You need to pass
		* @return Returns a pointer to a KineticClient. You need to pass
		* this pointer to KineticClient_CreateSession() to create
		* new connections.
		* Once you are finished will the `KineticClient`, and there
		* Once you are finished will the KineticClient, and there
		* are no active connections. The pointer should be released
		* with KineticClient_Shutdown()
		*/
		@@ -46,7 +46,7 @@ void KineticAdminClient_Shutdown(KineticClient * const client);
		/**
		* @brief Creates a session with the Kinetic Device per specified configuration.
		*
		* @param 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
		@@ -54,16 +54,16 @@ void KineticAdminClient_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
		* @param client The `KineticClient` pointer returned from KineticClient_Init()
		* @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`
		* @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`.
		* KineticSession.
		*/
		KineticStatus KineticAdminClient_CreateSession(KineticSessionConfig * const config,
		KineticClient * const client, KineticSession** session);
		@@ -71,7 +71,7 @@ KineticStatus KineticAdminClient_CreateSession(KineticSessionConfig * const conf
		/**
		* @brief Closes the connection to a host.
		*
		* @param session The connected `KineticSession` to close. The session
		* @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.
		*
		@@ -82,7 +82,7 @@ KineticStatus KineticAdminClient_DestroySession(KineticSession * const session);
		/**
		* @brief Sets the erase PIN of the Kinetic Device.
		*
		* @param session The connected `KineticSession` to close. The session
		* @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.
		@@ -94,7 +94,7 @@ KineticStatus KineticAdminClient_SetErasePin(KineticSession const * const sessio
		ByteArray old_pin, ByteArray new_pin);

		/**
		* @brief Executes a SecureErase command to erase all data from the Kinetic device.
		* @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.
		@@ -105,7 +105,7 @@ KineticStatus KineticAdminClient_SecureErase(KineticSession const * const sessio
		ByteArray pin);

		/**
		* @brief Executes an InstantErase command to erase all data from the Kinetic device.
		* @brief Executes an `InstantErase` operation 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.
		@@ -118,7 +118,7 @@ KineticStatus KineticAdminClient_InstantErase(KineticSession const * const sessi
		/**
		* @brief Sets the lock PIN of the Kinetic Device.
		*
		* @param session The connected `KineticSession` to close. The session
		* @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.
		@@ -130,7 +130,7 @@ KineticStatus KineticAdminClient_SetLockPin(KineticSession const * const session
		ByteArray old_pin, ByteArray new_pin);

		/**
		* @brief Executes a LOCK command to lock the Kinetic device.
		* @brief Executes a `LOCK` operation 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.
		@@ -141,7 +141,7 @@ KineticStatus KineticAdminClient_LockDevice(KineticSession const * const session
		ByteArray pin);

		/**
		* @brief Executes an UNLOCK command to unlock the Kinetic device.
		* @brief Executes an `UNLOCK` operation 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.
		@@ -152,7 +152,7 @@ KineticStatus KineticAdminClient_UnlockDevice(KineticSession const * const sessi
		ByteArray pin);

		/**
		* @brief Executes a GETLOG command to retrieve specific configuration and/or
		* @brief Executes a `GETLOG` operation to retrieve specific configuration and/or
		* operational data from the Kinetic Device.
		*
		* @param session The connected KineticSession to use for the operation
		@@ -160,19 +160,39 @@ KineticStatus KineticAdminClient_UnlockDevice(KineticSession const * const sessi
		* @param info KineticLogInfo pointer, which will be assigned to
		* a dynamically allocated structure populated with
		* the requested data, if successful. The client should
		* call free() on this pointer in order to free the root
		* and any nested structures.
		* call KineticAdminClient_FreeLogInfo() with this pointer
		* in order to free all allocated memory.
		* @param closure Optional closure. If specified, operation will be
		* executed in asynchronous mode, and closure callback
		* will be called upon completion in another thread.
		*
		* @return Returns 0 upon success, -1 or the Kinetic status code
		* upon failure
		* @return Returns the resulting KineticStatus
		*/
		KineticStatus KineticAdminClient_GetLog(KineticSession const * const session,
		KineticLogInfo_Type type,
		KineticLogInfo** info,
		KineticCompletionClosure* closure);
		/**
		* @brief Executes a `GETLOG` operation to retrieve device-specific log info
		* from the Kinetic Device via name/key.
		*
		* @param session The connected KineticSession to use for the operation
		* @param name Device specific name to retrieve info for.
		* @param info KineticLogInfo pointer, which will be assigned to
		* a dynamically allocated structure populated with
		* the requested data, if successful. The client should
		* call KineticAdminClient_FreeLogInfo() with this pointer
		* in order to free all allocated memory.
		* @param closure Optional closure. If specified, operation will be
		* executed in asynchronous mode, and closure callback
		* will be called upon completion in another thread.
		*
		* @return Returns the resulting KineticStatus
		*/
		KineticStatus KineticAdminClient_GetDeviceSpecificLog(KineticSession const * const session,
		ByteArray name,
		KineticLogInfo** info,
		KineticCompletionClosure* closure);

		/**
		* @brief Free the KineticLogInfo result from KineticClient_GetLog.
		@@ -195,19 +215,18 @@ KineticStatus KineticAdminClient_SetClusterVersion(KineticSession const * const
		int64_t version);

		/**
		* @brief Executes a SECURITY operation, setting one or more ACLs.
		* @brief Executes a `SECURITY` operation, setting one or more ACLs.
		*
		* @param session The connected KineticSession to use for the operation
		* @param ACLPath Path to a JSON file containing one or more ACLs.
		*
		* @return Returns 0 upon success, -1 or the Kinetic status code
		* upon failure.
		* @return Returns the resulting KineticStatus.
		*/
		KineticStatus KineticAdminClient_SetACL(KineticSession const * const session,
		const char *ACLPath);

		/**
		* @brief Executes a Firmware Download operation to update the firmware on the Kinetic device.
		* @brief Executes a `Firmware Download` operation to update the firmware on the Kinetic device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param fw_path Path to firmware update image file.

include/kinetic_client.h

+16 −16

Original line number	Diff line number	Diff line
		@@ -28,10 +28,10 @@
		*
		* @param config A configuration struct.
		*
		* @return Returns a pointer to a `KineticClient`. You need to pass
		* @return Returns a pointer to a KineticClient. You need to pass
		* this pointer to KineticClient_CreateSession() to create
		* new connections.
		* Once you are finished will the `KineticClient`, and there
		* Once you are finished will the KineticClient, and there
		* are no active connections. The pointer should be release
		* with KineticClient_Shutdown()
		*/
		@@ -48,7 +48,7 @@ void KineticClient_Shutdown(KineticClient * const client);
		/**
		* @brief Creates a session with the Kinetic Device per specified configuration.
		*
		* @param 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
		@@ -56,16 +56,16 @@ 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
		* @param client The `KineticClient` pointer returned from KineticClient_Init()
		* @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`
		* @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`.
		* KineticSession.
		*/
		KineticStatus KineticClient_CreateSession(KineticSessionConfig * const config,
		KineticClient * const client, KineticSession** session);
		@@ -73,7 +73,7 @@ KineticStatus KineticClient_CreateSession(KineticSessionConfig * const config,
		/**
		* @brief Closes the connection to a host.
		*
		* @param session The connected `KineticSession` to close. The session
		* @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.
		*
		@@ -82,7 +82,7 @@ KineticStatus KineticClient_CreateSession(KineticSessionConfig * const config,
		KineticStatus KineticClient_DestroySession(KineticSession * const session);

		/**
		* @brief Executes a NOOP command to test whether the Kinetic Device is operational.
		* @brief Executes a `NOOP` operation to test whether the Kinetic Device is operational.
		*
		* @param session The connected KineticSession to use for the operation.
		*
		@@ -91,7 +91,7 @@ KineticStatus KineticClient_DestroySession(KineticSession * const session);
		KineticStatus KineticClient_NoOp(KineticSession const * const session);

		/**
		* @brief Executes a PUT command to store/update an entry on the Kinetic Device.
		* @brief Executes a `PUT` operation to store/update an entry on the Kinetic Device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param entry Key/value entry for object to store. 'value' must
		@@ -110,7 +110,7 @@ KineticStatus KineticClient_Put(KineticSession const * const session,
		KineticCompletionClosure* closure);

		/**
		* @brief Executes a FLUSHALLDATA command to flush pending PUTs or DELETEs.
		* @brief Executes a `FLUSHALLDATA` operation to flush pending PUTs or DELETEs.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param closure Optional closure. If specified, operation will be
		@@ -123,7 +123,7 @@ KineticStatus KineticClient_Flush(KineticSession const * const session,
		KineticCompletionClosure* closure);

		/**
		* @brief Executes a GET command to retrieve an entry from the Kinetic Device.
		* @brief Executes a `GET` operation to retrieve an entry from the Kinetic Device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param entry Key/value entry for object to retrieve. 'value' will
		@@ -141,7 +141,7 @@ KineticStatus KineticClient_Get(KineticSession const * const session,
		KineticCompletionClosure* closure);

		/**
		* @brief Executes a GETPREVIOUS command to retrieve the next entry from the Kinetic Device.
		* @brief Executes a `GETPREVIOUS` operation to retrieve the next entry from the Kinetic Device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param entry Key/value entry for object to retrieve. 'value' will
		@@ -163,7 +163,7 @@ KineticStatus KineticClient_GetPrevious(KineticSession const * const session,
		KineticCompletionClosure* closure);

		/**
		* @brief Executes a GETNEXT command to retrieve the next entry from the Kinetic Device.
		* @brief Executes a `GETNEXT` operation to retrieve the next entry from the Kinetic Device.
		*
		* @param session The connected KineticSession to use for the operation.
		* @param entry Key/value entry for object to retrieve. 'value' will
		@@ -185,7 +185,7 @@ KineticStatus KineticClient_GetNext(KineticSession const * const session,
		KineticCompletionClosure* closure);

		/**
		* @brief Executes a DELETE command to delete an entry from the Kinetic Device
		* @brief Executes a `DELETE` operation to delete an entry from the Kinetic Device
		*
		* @param session The connected KineticSession to use for the operation.
		* @param entry Key/value entry for object to delete. 'value' is
		@@ -201,7 +201,7 @@ KineticStatus KineticClient_Delete(KineticSession const * const session,
		KineticCompletionClosure* closure);

		/**
		* @brief Executes a GETKEYRANGE command to retrieve a set of keys in the range
		* @brief Executes a `GETKEYRANGE` operation to retrieve a set of keys in the range
		* specified range from the Kinetic Device
		*
		* @param session The connected KineticSession to use for the operation
		@@ -222,7 +222,7 @@ KineticStatus KineticClient_GetKeyRange(KineticSession const * const session,
		KineticCompletionClosure* closure);

		/**
		* @brief Executes a PEER2PEERPUSH operation allows a client to instruct a Kinetic
		* @brief Executes a `PEER2PEERPUSH` operation allows a client to instruct a Kinetic
		* Device to copy a set of keys (and associated value and metadata) to another
		* Kinetic Device.
		*

include/kinetic_types.h

+3 −2

Original line number	Diff line number	Diff line
		@@ -195,6 +195,8 @@ typedef enum {
		KINETIC_STATUS_NOT_AUTHORIZED, ///< Authorization failure
		KINETIC_STATUS_INVALID_FILE, ///< Specified file does not exist or could not be read/writtten
		KINETIC_STATUS_REQUEST_REJECTED, ///< No request was attempted.
		KINETIC_STATUS_DEVICE_NAME_REQUIRED, ///< A device name is required, but was empty
		KINETIC_STATUS_INVALID_LOG_TYPE, ///< The device log type specified was invalid
		KINETIC_STATUS_COUNT ///< Number of status codes in KineticStatusDescriptor
		} KineticStatus;

		@@ -296,8 +298,7 @@ typedef enum {
		KINETIC_DEVICE_INFO_TYPE_CONFIGURATION,
		KINETIC_DEVICE_INFO_TYPE_STATISTICS,
		KINETIC_DEVICE_INFO_TYPE_MESSAGES,
		KINETIC_DEVICE_INFO_TYPE_LIMITS,
		KINETIC_DEVICE_INFO_TYPE_DEVICE,
		KINETIC_DEVICE_INFO_TYPE_LIMITS
		} KineticLogInfo_Type;
		typedef struct {
		char* name;

src/lib/kinetic_admin_client.c

+26 −1

Original line number	Diff line number	Diff line
		@@ -192,11 +192,36 @@ KineticStatus KineticAdminClient_GetLog(KineticSession const * const session,
		assert(session->connection != NULL);
		assert(info != NULL);

		KineticProto_Command_GetLog_Type protoType =
		KineticLogInfo_Type_to_KineticProto_Command_GetLog_Type(type);
		if (protoType == KINETIC_PROTO_COMMAND_GET_LOG_TYPE_INVALID_TYPE) {
		return KINETIC_STATUS_INVALID_LOG_TYPE;
		}

		KineticOperation* operation = KineticAllocator_NewOperation(session->connection);
		if (operation == NULL) {return KINETIC_STATUS_MEMORY_ERROR;}

		// Initialize request
		KineticBuilder_BuildGetLog(operation, protoType, BYTE_ARRAY_NONE, info);

		// Execute the operation
		return KineticController_ExecuteOperation(operation, closure);
		}

		KineticStatus KineticAdminClient_GetDeviceSpecificLog(KineticSession const * const session,
		ByteArray name,
		KineticLogInfo** info,
		KineticCompletionClosure* closure)
		{
		assert(session != NULL);
		assert(session->connection != NULL);
		assert(info != NULL);

		KineticOperation* operation = KineticAllocator_NewOperation(session->connection);
		if (operation == NULL) {return KINETIC_STATUS_MEMORY_ERROR;}

		// Initialize request
		KineticBuilder_BuildGetLog(operation, type, info);
		KineticBuilder_BuildGetLog(operation, KINETIC_PROTO_COMMAND_GET_LOG_TYPE_DEVICE, name, info);

		// Execute the operation
		return KineticController_ExecuteOperation(operation, closure);