kinetic-c  v0.12.0
Seagate Kinetic Protocol Client Library for C
Functions
kinetic_admin_client.c File Reference
#include "kinetic_admin_client.h"
#include "kinetic_types_internal.h"
#include "kinetic_controller.h"
#include "kinetic_operation.h"
#include "kinetic_builder.h"
#include "kinetic_allocator.h"
#include "kinetic_auth.h"
#include "kinetic_device_info.h"
#include "kinetic_acl.h"
#include "kinetic_logger.h"

Go to the source code of this file.

Functions

KineticClient * KineticAdminClient_Init (KineticClientConfig *config)
 Initializes the Kinetic Admin API and configures logging. More...
 
void KineticAdminClient_Shutdown (KineticClient *const client)
 Performs shutdown/cleanup of the kinetic-c client library. More...
 
KineticStatus KineticAdminClient_CreateSession (KineticSessionConfig *const config, KineticClient *const client, KineticSession **session)
 Creates a session with the Kinetic Device per specified configuration. More...
 
KineticStatus KineticAdminClient_DestroySession (KineticSession *const session)
 Closes the connection to a host. More...
 
KineticStatus KineticAdminClient_SetErasePin (KineticSession *const session, ByteArray old_pin, ByteArray new_pin)
 Sets the erase PIN of the Kinetic Device. More...
 
KineticStatus KineticAdminClient_SecureErase (KineticSession *const session, ByteArray pin)
 Executes a SecureErase command to erase all data from the Kinetic device. More...
 
KineticStatus KineticAdminClient_InstantErase (KineticSession *const session, ByteArray pin)
 Executes an InstantErase operation to erase all data from the Kinetic device. More...
 
KineticStatus KineticAdminClient_SetLockPin (KineticSession *const session, ByteArray old_pin, ByteArray new_pin)
 Sets the lock PIN of the Kinetic Device. More...
 
KineticStatus KineticAdminClient_LockDevice (KineticSession *const session, ByteArray pin)
 Executes a LOCK operation to lock the Kinetic device. More...
 
KineticStatus KineticAdminClient_UnlockDevice (KineticSession *const session, ByteArray pin)
 Executes an UNLOCK operation to unlock the Kinetic device. More...
 
KineticStatus KineticAdminClient_GetLog (KineticSession *const session, KineticLogInfo_Type type, KineticLogInfo **info, KineticCompletionClosure *closure)
 Executes a GETLOG operation to retrieve specific configuration and/or operational data from the Kinetic Device. More...
 
KineticStatus KineticAdminClient_GetDeviceSpecificLog (KineticSession *const session, ByteArray name, KineticLogInfo **info, KineticCompletionClosure *closure)
 Executes a GETLOG operation to retrieve device-specific log info from the Kinetic Device via name/key. More...
 
void KineticClient_FreeLogInfo (KineticSession *const session, KineticLogInfo *info)
 
KineticStatus KineticAdminClient_SetClusterVersion (KineticSession *const session, int64_t version)
 Updates the cluster version of the Kinetic Device. More...
 
KineticStatus KineticAdminClient_SetACL (KineticSession *const session, const char *ACLPath)
 Executes a SECURITY operation, setting one or more ACLs. More...
 
KineticStatus KineticAdminClient_UpdateFirmware (KineticSession *const session, char const *const fw_path)
 Executes a Firmware Download operation to update the firmware on the Kinetic device. More...
 

Function Documentation

KineticClient* KineticAdminClient_Init ( KineticClientConfig config)

Initializes the Kinetic Admin API and configures logging.

Parameters
configA configuration struct.
Returns
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 are no active connections. The pointer should be released with KineticClient_Shutdown()

Definition at line 36 of file kinetic_admin_client.c.

References KineticClient_Init().

void KineticAdminClient_Shutdown ( KineticClient *const  client)

Performs shutdown/cleanup of the kinetic-c client library.

Definition at line 41 of file kinetic_admin_client.c.

References KineticClient_Shutdown().

KineticStatus KineticAdminClient_CreateSession ( KineticSessionConfig *const  config,
KineticClient *const  client,
KineticSession **  session 
)

Creates a session with the Kinetic Device per specified configuration.

Parameters
configKineticSessionConfig 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) .pin PIN to use for PIN-based operations
clientThe KineticClient pointer returned from KineticClient_Init()
sessionPointer to a KineticSession pointer that will be populated with the allocated/created session upon success.
Returns
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.

Definition at line 46 of file kinetic_admin_client.c.

References KineticClient_CreateSession().

KineticStatus KineticAdminClient_DestroySession ( KineticSession *const  session)

Closes the connection to a host.

Parameters
sessionThe 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.
Returns
Returns the resulting KineticStatus.

Definition at line 52 of file kinetic_admin_client.c.

References KineticClient_DestroySession().

KineticStatus KineticAdminClient_SetErasePin ( KineticSession *const  session,
ByteArray  old_pin,
ByteArray  new_pin 
)

Sets the erase PIN of the Kinetic Device.

Parameters
sessionThe 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.
old_pinOld erase PIN to change.
new_pinNew erase PIN to change to.
Returns
Returns the resulting KineticStatus.

Definition at line 58 of file kinetic_admin_client.c.

References ByteArray::data, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_MISSING_PIN, KINETIC_STATUS_SUCCESS, KineticAllocator_NewOperation(), KineticAuth_EnsureSslEnabled(), KineticBuilder_BuildSetPin(), KineticController_ExecuteOperation(), and ByteArray::len.

KineticStatus KineticAdminClient_SecureErase ( KineticSession *const  session,
ByteArray  pin 
)

Executes a SecureErase command to erase all data from the Kinetic device.

Parameters
sessionThe connected KineticSession to use for the operation.
pinPIN to send with operation, which must match the configured erase PIN.
Returns
Returns the resulting KineticStatus.

Definition at line 78 of file kinetic_admin_client.c.

References ByteArray::data, KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_MISSING_PIN, KINETIC_STATUS_SUCCESS, KineticAllocator_NewOperation(), KineticAuth_EnsureSslEnabled(), KineticBuilder_BuildErase(), KineticController_ExecuteOperation(), and ByteArray::len.

KineticStatus KineticAdminClient_InstantErase ( KineticSession *const  session,
ByteArray  pin 
)

Executes an InstantErase operation to erase all data from the Kinetic device.

Parameters
sessionThe connected KineticSession to use for the operation.
pinPIN to send with operation, which must match the configured erase PIN.
Returns
Returns the resulting KineticStatus.

Definition at line 99 of file kinetic_admin_client.c.

References ByteArray::data, KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_MISSING_PIN, KINETIC_STATUS_SUCCESS, KineticAllocator_NewOperation(), KineticAuth_EnsureSslEnabled(), KineticBuilder_BuildErase(), KineticController_ExecuteOperation(), and ByteArray::len.

KineticStatus KineticAdminClient_SetLockPin ( KineticSession *const  session,
ByteArray  old_pin,
ByteArray  new_pin 
)

Sets the lock PIN of the Kinetic Device.

Parameters
sessionThe 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.
old_pinOld erase PIN to change.
new_pinNew erase PIN to change to.
Returns
Returns the resulting KineticStatus.

Definition at line 121 of file kinetic_admin_client.c.

References ByteArray::data, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_MISSING_PIN, KINETIC_STATUS_SUCCESS, KineticAllocator_NewOperation(), KineticAuth_EnsureSslEnabled(), KineticBuilder_BuildSetPin(), KineticController_ExecuteOperation(), and ByteArray::len.

KineticStatus KineticAdminClient_LockDevice ( KineticSession *const  session,
ByteArray  pin 
)

Executes a LOCK operation to lock the Kinetic device.

Parameters
sessionThe connected KineticSession to use for the operation.
pinPIN to send with operation, which must match the configured lock PIN.
Returns
Returns the resulting KineticStatus.

Definition at line 141 of file kinetic_admin_client.c.

References ByteArray::data, KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_MISSING_PIN, KINETIC_STATUS_SUCCESS, KineticAllocator_NewOperation(), KineticAuth_EnsureSslEnabled(), KineticBuilder_BuildLockUnlock(), KineticController_ExecuteOperation(), and ByteArray::len.

KineticStatus KineticAdminClient_UnlockDevice ( KineticSession *const  session,
ByteArray  pin 
)

Executes an UNLOCK operation to unlock the Kinetic device.

Parameters
sessionThe connected KineticSession to use for the operation.
pinPIN to send with operation, which must match the configured lock PIN.
Returns
Returns the resulting KineticStatus.

Definition at line 162 of file kinetic_admin_client.c.

References ByteArray::data, KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_MISSING_PIN, KINETIC_STATUS_SUCCESS, KineticAllocator_NewOperation(), KineticAuth_EnsureSslEnabled(), KineticBuilder_BuildLockUnlock(), KineticController_ExecuteOperation(), and ByteArray::len.

KineticStatus KineticAdminClient_GetLog ( KineticSession *const  session,
KineticLogInfo_Type  type,
KineticLogInfo **  info,
KineticCompletionClosure closure 
)

Executes a GETLOG operation to retrieve specific configuration and/or operational data from the Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation
typeKineticLogDataType specifying data type to retrieve.
infoKineticLogInfo 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.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns the resulting KineticStatus

Definition at line 183 of file kinetic_admin_client.c.

References BYTE_ARRAY_NONE, COM__SEAGATE__KINETIC__PROTO__COMMAND__GET_LOG__TYPE__INVALID_TYPE, KINETIC_ASSERT, KINETIC_STATUS_INVALID_LOG_TYPE, KINETIC_STATUS_MEMORY_ERROR, KineticAllocator_NewOperation(), KineticBuilder_BuildGetLog(), KineticController_ExecuteOperation(), and KineticLogInfo_Type_to_Com__Seagate__Kinetic__Proto__Command__GetLog__Type().

KineticStatus KineticAdminClient_GetDeviceSpecificLog ( KineticSession *const  session,
ByteArray  name,
KineticLogInfo **  info,
KineticCompletionClosure closure 
)

Executes a GETLOG operation to retrieve device-specific log info from the Kinetic Device via name/key.

Parameters
sessionThe connected KineticSession to use for the operation
nameDevice specific name to retrieve info for.
infoKineticLogInfo 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.
closureOptional closure. If specified, operation will be executed in asynchronous mode, and closure callback will be called upon completion in another thread.
Returns
Returns the resulting KineticStatus

Definition at line 207 of file kinetic_admin_client.c.

References COM__SEAGATE__KINETIC__PROTO__COMMAND__GET_LOG__TYPE__DEVICE, KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KineticAllocator_NewOperation(), KineticBuilder_BuildGetLog(), and KineticController_ExecuteOperation().

void KineticClient_FreeLogInfo ( KineticSession *const  session,
KineticLogInfo info 
)

Definition at line 225 of file kinetic_admin_client.c.

References KINETIC_ASSERT, and KineticLogInfo_Free().

KineticStatus KineticAdminClient_SetClusterVersion ( KineticSession *const  session,
int64_t  version 
)

Updates the cluster version of the Kinetic Device.

Parameters
sessionThe connected KineticSession to use for the operation.
versionNew cluster version.
Returns
Returns the resulting KineticStatus.

Definition at line 236 of file kinetic_admin_client.c.

References KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KineticAllocator_NewOperation(), KineticBuilder_BuildSetClusterVersion(), and KineticController_ExecuteOperation().

KineticStatus KineticAdminClient_SetACL ( KineticSession *const  session,
const char *  ACLPath 
)

Executes a SECURITY operation, setting one or more ACLs.

Parameters
sessionThe connected KineticSession to use for the operation
ACLPathPath to a JSON file containing one or more ACLs.
Returns
Returns the resulting KineticStatus.

Definition at line 248 of file kinetic_admin_client.c.

References ACL_OK, KINETIC_ASSERT, KINETIC_STATUS_ACL_ERROR, KINETIC_STATUS_INVALID_REQUEST, KINETIC_STATUS_MEMORY_ERROR, KineticACL_LoadFromFile(), KineticAllocator_NewOperation(), KineticBuilder_BuildSetACL(), and KineticController_ExecuteOperation().

KineticStatus KineticAdminClient_UpdateFirmware ( KineticSession *const  session,
char const *const  fw_path 
)

Executes a Firmware Download operation to update the firmware on the Kinetic device.

Parameters
sessionThe connected KineticSession to use for the operation.
fw_pathPath to firmware update image file.
Returns
Returns the resulting KineticStatus.

Definition at line 276 of file kinetic_admin_client.c.

References KINETIC_ASSERT, KINETIC_STATUS_MEMORY_ERROR, KINETIC_STATUS_SUCCESS, KineticAllocator_NewOperation(), KineticBuilder_BuildUpdateFirmware(), and KineticController_ExecuteOperation().