BSAGetObject
Get an object.
SYNOPSIS
#include <xbsa.h>
int BSAGetObject(BSA_Handle bsaHandle, BSA_ObjectDescriptor *objectDescriptorPtr, BSA_DataBlock32 *dataBlockPtr)
DESCRIPTION
BSAGetObject() retrieves the NetBackup XBSA object identified by the copyId and prepares the NetBackup XBSA Interface to retrieve the XBSA object data. It initiates the communication with the NetBackup server to retrieve the object.
The dataBlockPtr parameter in the BSAGetObject() call allows the caller to obtain information about the buffer structure required by the NetBackup XBSA interface. The caller obtains the NetBackup XBSA object data through subsequent BSAGetData() calls. The caller must terminate the receipt of the data by using the BSAEndData() call.
PARAMETERS
BSA_Handle bsaHandle (I) | This parameter is the handle that associates this call with a previous BSAInit() call. |
BSA_ObjectDescriptor *objectDescriptorPtr (I) | This parameter is a pointer to a data area used to pass the NetBackup XBSA object's copyId to the NetBackup XBSA interface. |
BSA_DataBlock32 *dataBlockPtr (O) | This parameter is a pointer to a structure that is used to obtain the details of the required buffer structure. |
EXTENDED DESCRIPTION
It is mandatory that the copyId field in the BSA_ObjectDescriptor structure is set as this is the only field that is checked. A copyId value of zero cannot identify a valid XBSA object. BSAGetObject() matches the copyId field for equality.
The dataBlockPtr structure does not point to an actual buffer. All values in the dataBlockPtr should be zero, and are overwritten. The structure is used by the NetBackup XBSA interface to provide the XBSA application with the interface's preference for the structure of the data blocks that are used to pass the NetBackup XBSA object's data. The XBSA application should examine the values returned to determine the buffer structure that it should create. The significance of the returned values is as follows:
bufferLen == 0 | NetBackup has no restrictions on the buffer length. No trailer portion is required. |
bufferLen != 0 | NetBackup accepts buffers that are at least bufferLen bytes in length (minimum length). The length of the trailer portion of buffers is: trailerBytes >= (bufferLen - numBytes - headerBytes). |
numBytes == 0 | NetBackup has no restrictions on the length of the data portion of the buffer. |
numBytes != 0 | The minimum length of the data portion of buffers accepted by NetBackup must be numBytes bytes. If the interface provides a larger data portion, NetBackup may take advantage of it. |
headerBytes == 0 | NetBackup only accepts buffers with no header portion. |
headerBytes != 0 | The length of the header portion of buffers accepted by NetBackup is headerBytes bytes. |
bufferPtr | Not used. |
The values returned by the call to BSAGetObject() remain in effect for the duration of the data transfer of the NetBackup XBSA object being retrieved, that is, until the next BSAEndData() call. The NetBackup XBSA interface currently does not have any header or trailer requirements, so the full buffer specified can be used by the XBSA application. This is documented for completeness with the XBSA specification and to allow future use of these fields as specified by the XBSA specifications.
RETURN VALUE
The following return codes are returned by this function:
BSA_RC_ABORT_SYSTEM_ERROR | System detected error, operation aborted. |
BSA_RC_ACCESS_FAILURE | Access to the requested XBSA object is not possible. Cannot retrieve the XBSA object with the given copyId. |
BSA_RC_INVALID_CALL_SEQUENCE | The sequence of API calls is incorrect. |
BSA_RC_INVALID_COPYID | The copyId cannot be zero. |
BSA_RC_INVALID_HANDLE | The handle used to associate this call with a previous BSAInit() call is invalid. |
BSA_RC_NULL_ARGUMENT | A NULL pointer was encountered in one of the arguments. |
BSA_RC_OBJECT_NOT_FOUND | The given copyId does not exist. |
BSA_RC_SUCCESS | The function succeeded. |