Type Definitions and Data Structures

Type Definitions

The 3rd column in the table above is not mandatory. The type definitions must be true to the what the type name specifies.

For 64 bit architectures, and architectures that support 64 bit quantities as a simple type, the BSA_UInt64 type may not be a structure.

Enumerated Types

BSA_CopyType

 

typedef enum {
    BSA_CopyType_ANY = 1,
    BSA_CopyType_ARCHIVE = 2,
    BSA_CopyType_BACKUP = 3
} BSA_CopyType;

The meaning of the enumeration values is as follows:

BSA_ObjectStatus

 

typedef enum {
    BSA_ObjectStatus_ANY = 1,
    BSA_ObjectStatus_MOST_RECENT = 2,
    BSA_ObjectStatus_NOT_MOST_RECENT = 3
} BSA_ObjectStatus;

The meaning of the enumeration values is as follows:

BSA_ObjectType

 

typedef enum {
    BSA_ObjectType_ANY  = 1,
    BSA_ObjectType_FILE    = 2,
    BSA_ObjectType_DIRECTORY = 3,
    BSA_ObjectType_OTHER = 4
} BSA_ObjectType;

The meaning of the enumeration values is as follows:

BSA_Vote

 

typedef enum {
    BSA_Vote_COMMIT = 1,
    BSA_Vote_ABORT  = 2
} BSA_Vote;

The meaning of the enumeration values is as follows:

Constant Values

Data Structures

BSA_ApiVersion

 

typedef struct {
    BSA_UInt16    issue;
    BSA_UInt16    version;
    BSA_UInt16    level;
} BSA_ApiVersion;

The usage of the structure fields is defined as follows:

issue

Issue Number of the XBSA Specification

version

Version Number of the XBSA Specification

level

Implementation-defined version number

For implementations of the XBSA Preliminary Specification (Document Number P424), the values of the BSA_ApiVersion structure were implementation-dependent. For implementations of the XBSA Technical Standard (this document - C425), the values should be 1,1,X:

* = implementation-dependent

BSA_DataBlock32

 

typedef struct {
    BSA_UInt32  bufferLen;
    BSA_UInt32  numBytes;
    BSA_UInt32  headerBytes;
    BSA_ShareId shareId;
    BSA_UInt32  shareOffset;
    void       *bufferPtr
} BSA_DataBlock32;

The usage of the structure fields is defined as follows:

The values assigned to the various structure fields would always obey the following relationships:

 

bufferLen    >= headerBytes + numBytes
trailerBytes == (bufferLen - numBytes - headerBytes)

The layout of the buffer is as follows:

The header and trailer portions of the buffer are reserved for the use of the Backup Service, and should not be modified by the XBSA Application. The XBSA Application should only write to the data portion of the buffer, which is the only portion used for transferring application data.

The sizes for the header and trailer portions of the buffer that are required by the Backup Service are obtained by calling BSACreateObject() or BSAGetObject().

BSA_ObjectDescriptor

 

#include <time.h>

typedef struct {
    BSA_UInt32          rsv1;
    BSA_ObjectOwner     objectOwner;
    BSA_ObjectName      objectName;
    struct tm           createTime;
    BSA_CopyType        copyType;
    BSA_UInt64          copyId;
    BSA_UInt64          restoreOrder;
    char                rsv2[31];
    char                rsv3[31];
    BSA_UInt64          estimatedSize;
    char                resourceType[BSA_MAX_RESOURCETYPE];
    BSA_ObjectType      objectType;
    BSA_ObjectStatus    objectStatus;
    char                rsv4[31];
    char                objectDescription[MAX_RC_OBJECTDESCRIPTION];
    unsigned char       objectInfo[BSA_MAX_OBJECTINFO];
} BSA_ObjectDescriptor;

Some of the fields in this structure are supplied by the XBSA Application (Direction = in), and some by the Backup Service (Direction = out). Some fields are optional.

The usage of the structure fields is defined as follows:

All values in a BSA_ObjectDescriptor must be valid before the BSA_ObjectDescriptor as a whole is valid. For enumerations valid values exclude the enumeration "ANY". For strings valid values are null-terminated.

The optional string value is the empty string. The optional restoreOrder value is zero. The optional objectInfo value is all zeros (that is, a zero-filled field).

The mandatory objectName must have a non-empty string in the pathName field. The mandatory createTime must be a valid time in UTC. The mandatory copyId must be non-zero. The mandatory resourceType must have a non-empty string value.

BSA_ObjectName

 

typedef struct {
    char  objectSpaceName[BSA_MAX_OBJECTSPACENAME];
    char  pathName[BSA_MAX_PATHNAME];
} BSA_ObjectName;

The usage of the structure fields is defined as follows:

An objectSpaceName is an optionally defined, fixed-length character string. It identifies a logical space, called an Object space, in which the object belongs. For example, an Object space may be used to identify a storage volume (for example, a disk partition, or a floppy disk), or a database in the XBSA Application's domain.

The concept of an Object space is used to provide a primary grouping of XBSA Objects, which may be used for object search by a user and/or for object management by the Backup Service. Additional groupings are provided by Filespec and by object attributes. Examples of an objectSpaceName are C: Drive and VolumeLabel=XYZ.

A pathName is a hierarchical character string that identifies an XBSA Object within an ObjectSpace.

An example of a pathName for the backup copy of a UNIX file may be its original path name and file name, for example, /documents/opengroup/backup.proposal.

The value of the delimiter used to separate name components can be obtained by calling BSAGetEnvironment().

BSA_ObjectOwner

 

typedef struct {
    char  bsa_ObjectOwner[BSA_MAX_BSAOBJECT_OWNER];
    char  app_ObjectOwner[BSA_MAX_APPOBJECT_OWNER];
} BSA_ObjectOwner;

The usage of the structure fields is defined as follows:

The bsa_ObjectOwner identifies an XBSA Application (for example, an XBSA Application associated with a UNIX file system located at a certain node).

An app_ObjectOwner is an optional name, such as an actual end-user name, provided by the respective XBSA Application, so that the Backup Service can provide assistance to support application-specific access control by optimizing access for the given app_ObjectOwner.

The app_ObjectOwner may have multiple components defined in the application, such as a group name and a user id. In general, it is a hierarchical character string. An app_ObjectOwner is not registered with the Backup Service. Its registration and authentication is the XBSA Application's responsibility. Examples of a typical app_ObjectOwner are Smith, AccountingDept.Clerk1 and * (unspecified).

BSA_QueryDescriptor

 

#include <time.h>;
typedef struct {
    BSA_ObjectOwner     objectOwner;
    BSA_ObjectName      objectName;
    struct tm           rsv1;
    struct tm           rsv2;
    struct tm           rsv3;
    struct tm           rsv4;
    BSA_CopyType        copyType;
    char                rsv5[31];
    char                rsv6[31];
    char                rsv7[31];
    BSA_ObjectType      objectType;
    BSA_ObjectStatus    objectStatus;
    char                rsv8[100];
} BSA_QueryDescriptor;

The usage of the structure fields is defined as follows:

BSA_SecurityToken

 

typedef char BSA_SecurityToken[BSA_MAX_TOKEN_SIZE];