Overview of Backup Services API

The Open Backup Services API is a set of procedures which may be called up, available in a dynamic or static library provided by a vendor implementing a Backup Service. For the rest of this Technical Standard, the terms API or XBSA refer to this Open Backup Services API.

A synchronous interface in the C language is defined. If an application needs asynchronous behavior, it can be achieved by using its process or thread mechanisms.

The following sections in this chapter give a brief overview of the API calls and their intended usage. A detailed specification of the procedures comprising the API is given in the manual-page definitions in Backup Services API Definitions .

Type Definitions and Data Structures defines the data type definitions and data structures used in the API.

Initialization and Authentication

BSAInit() may authenticate the caller using a security token; the exact definition and use of this security token is implementation dependent. If a NULL security token is provided, the Backup Service can use a default, implementation-dependent security mechanism. In addition to those environmental parameters defined in this Technical Standard, there may also be additional, implementation dependent environmental parameters to the BSAInit() call.

A potential failure to authenticate the XBSA Client will cause the BSAInit() call to return BSA_RC_AUTHENTICATION_FAILURE. The XBSA Client will have to communicate with the security subsystem that is being used by the Backup Service to resolve this failure. The XBSA itself does not provide details about the reason of the authentication failure, or the means for correcting the authentication failure.

Transactions

If a transaction is aborted either by a BSAEndTxn() or BSATerminate() call, then the effect of all the calls made within the transaction is nullified. If a transaction is committed, then the effect of all the calls within the transaction is made permanent.

Within a single session, transactions cannot be nested and cannot overlap. Transactions are categorized into the following types:

• Object modification transactions - in which objects may be created or deleted.

• Object retrieval transactions - in which objects may only be queried or retrieved. (This type of transaction provides no functional benefit for the calling XBSA Application, and is only included for completeness.)

The type of a transaction is established by the first create/delete/retrieve operation performed. Attempts to mix operations in a transaction will result in a BSA_RC_INVALID_CALL_SEQUENCE error. The permissible call sequences are defined later in this chapter.

The following example illustrates the call pattern that may be used by a caller who, in one transaction, loops through a list of object names to backup each object.

 


if ((rc = BSAInit(bsaHandlePtr, tokenPtr,
                  userNamePtr, environmentPtr) ) != BSA_RC_SUCCESS) {
   <error processing>;
}

if ((rc = BSABeginTxn(bsaHandle) ) != BSA_RC_SUCCESS) {
    <error processing>;
}

<loop through all object names> {
    if ((rc = BSACreateObject(bsaHandle, objectDescriptorPtr,
                              dataBlkPtr)) != BSA_RC_SUCCESS) {
        <error processing>;
    }

    <loop through all data for one object> {
        if ((rc = BSASendData(bsaHandle,
                              dataBlkPtr) ) != BSA_RC_SUCCESS) {
            <error processing>;
        }

    } /* loop through all data for one object */

    if ((rc = BSAEndData(bsaHandle) ) != BSA_RC_SUCCESS) {
        <error processing>;
    }
} /* loop through all object names */

if ((rc = BSAEndTxn(bsaHandle,BSA_COMMIT) ) != BSA_RC_SUCCESS) {
    <error processing>;
}

if ((rc = BSATerminate(bsaHandle) ) != BSA_RC_SUCCESS) {
    <error processing>;
}

In this example, the data for each of the backup copy objects may be buffered by the API before sending it to the Backup Service.

Backup and Archive

The ability to pass data in buffers allows an XBSA Application to use any buffering technique that is appropriate to ensure consistency or to improve performance. When data is passed in buffers, all the data for one object must be passed, in the proper sequence, before any other operation is started.

A scenario for creating a backup copy of an object is shown in Creating a Backup Copy of an Object .

Restore and Retrieve

The BSAGetObject() call is used to restore (from a backup copy) or retrieve (from an archive copy) objects. The BSAGetData() call is used to get data for the object in buffers, and the BSAEndData() call is to signal the end of getting data for the object. A scenario for restoring an object is shown in Restoring an Object .

Query

The query is based on a subset of the Object Descriptor attributes, contained in a Query Descriptor. The result of a query can return Object Descriptors, but never XBSA Object Data. If the result is multiple Object Descriptors, the query result is retrieved one Object Descriptor at a time by using a succession of BSAGetNextQueryObject() calls.

The XBSA Application can retrieve the XBSA Object Data by using the BSAGetObject() call with the copyId from one of the object descriptors returned by the query.

For details of the BSA_QueryDescriptor structure, see BSA_QueryDescriptor .

API Call Sequences

In the call sequence diagrams, the following conventions are used:

• States have arbitrary names.

• Function names have been shortened by dropping the "BSA" prefix.

• States from which BSAEndTxn(BSA_COMMIT) can be called successfully are indicated by a double box and named using bold font. Attempts to call BSAEndTxn(BSA_COMMIT) from any other state will return a BSA_RC_TRANSACTION_ABORTED error.

Leaving the "Transaction" state with other than a successful call of BSAEndTxn(BSA_COMMIT) will cause the transaction to be aborted. If the transaction was creating or deleting an object, that object will not be created or deleted. Apart from this, a transaction does not have any other side effect. In particular, the state of the storage media is not restored to the state just before the start of the aborted transaction.

Since getting or querying an object does not alter the state of the object, leaving the transaction has no side effects.

Buffers

However, to allow the Backup Service to influence how buffers should be allocated, and to provide the Backup Service with the ability to reserve private sections in certain buffers, several conventions are used in the XBSA.

Buffer Size

The parameter that specifies the size is a pointer, so that the Backup Service can alter the parameter. The size is always in bytes. If the size is adequate and a valid buffer is given, the Backup Service will copy the requested data into the buffer and set the actual size in the size parameter.

If the size is inadequate, the Backup Service will not copy the data into the buffer. It will set the size parameter to the actual size of the data to be copied and return from the function call with BSA_RC_BUFFER_TOO_SMALL. This allows the XBSA Application to allocate a buffer of adequate size and to call the function again.

The functions that use this convention are BSAGetEnvironment() and BSAQueryServiceProvider().

Private Buffer Space

• Header
  A contiguous area starting at offset 0 (that is, the start of the buffer)

• Trailer
  A contiguous area that ends at the end of the buffer (that is, the tail of the buffer)

The area reserved for the XBSA Application is the:

• Data Segment
  A contiguous area that lies in between the Header and Trailer

To make this preference known to the XBSA Application, the Backup Service sets certain parameters in the BSA_DataBlock32 structure when a data transfer is initiated. Specifically, when the XBSA Application issues either the BSACreateObject() call or the BSAGetObject() call, the BSA_DataBlock32 structure is not used for passing data but for passing the Backup Service's preference. The parameters that must be set by the Backup Service, and their meaning, are given in Parameters in the BSA_DataBlock32 Structure .

Subsequent calls to BSAGetData() or BSASendData() must adhere to the preferences that were specified by the Backup Service. The relationship between the areas, and their mapping to the fields of the BSA_DataBlock32 structure is described in BSA_DataBlock32 .

The Backup Service can write anything into the header and trailer area of the actual buffer, as specified by the bufferPtr parameter in the BSA_DataBlock32 structure.

Use of BSA_DataBlock32 in BSASendData()

Use of BSA_DataBlock32 in BSAGetData()

• numBytes
  Set the actual number of bytes copied into the data segment.

The Backup Service is not allowed to change any of the other parameters.

Shared Memory

The shareId specifies an identifier that can be used by the Backup Service to map the memory in which the buffer resides into its address space. A special typedef, BSA_ShareId, is used to define the shareId field using a type appropriate for the operating environment. For UNIX systems, this is based on the shared memory semantics defined in the Single UNIX Specification, System Interfaces and Headers, Issue 5 (see reference XSH, Issue 5) and the shareId is the shmid identifier obtained by calling the shmget() function. For NT systems, it is a file handle which will allow the Backup Service to map the file in memory.

The shareOffset specifies where in shared memory the buffer starts.

The semantics for the shareId are given in Parameters in the BSA_DataBlock32 Structure .

Since the client may be using multiple buffers, it is not guaranteed that only one shareId is used in the object data transfers. It is guaranteed, however, that a shareId itself will not change during a session. In other words, the XBSA Client is not allowed to re-map a shareId within a session once it has been made available to the Backup Service. In this way the Backup Service can keep a simple lookup table to see whether the shareId is currently mapped in its address space.

The following two sections describe how shared memory buffers are used in the UNIX and Microsoft Windows NT operating systems.

Shared Memory on UNIX

• The client performs either a BSACreateObject() or BSAGetObject() call to start the transfer and receives the buffer parameters.

• The client allocates a buffer in shared memory, thereby receiving a shared memory identifier. The client fills the buffer with data, if necessary.

• The client calls BSASendData() or BSAGetData() with the buffer parameters and the identifier of the shared memory block it previously allocated.

• The library implementation forwards the information to a different process, which will have to map the shared memory into its address space. This process can use shmctl() to retrieve the size of the shared memory segment, and use shmat() to attach the memory to its address space. Once attached, it uses the shareOffset to locate the actual buffer, and from there the normal BSA_DataBlock32 rules apply.

Shared Memory on NT

• The client performs either a BSACreateObject() or BSAGetObject() call to start the transfer and receives the buffer parameters.

• The client allocates a buffer in shared memory, thereby receiving a file handle. The shared memory is set up by creating a file-mapping object using CreateFileMapping(), and mapping it the client's address space with MapViewOfFile(). The client fills the buffer with data, if necessary.

• The client calls BSASendData() or BSAGetData() with the buffer parameters and the file handle of the file it used for mapping the shared memory.

• The library implementation forwards the information, including the process ID of the client, to a different process. This process will have to duplicate the handle using OpenProcess() and DuplicateHandle(), and map the file in its address space with MapViewOfFile(). Once mapped, it uses the shareOffset to locate the actual buffer, and from there the normal BSA_DataBlock32 rules apply.

For details of the interfaces, refer to the Microsoft Windows NT documentation.