clCkptApi.h

Go to the documentation of this file.

/*
 * Copyright (C) 2002-2012 OpenClovis Solutions Inc.  All Rights Reserved.
 *
 * This file is available  under  a  commercial  license  from  the
 * copyright  holder or the GNU General Public License Version 2.0.
 * 
 * The source code for  this program is not published  or otherwise 
 * divested of  its trade secrets, irrespective  of  what  has been 
 * deposited with the U.S. Copyright office.
 * 
 * This program is distributed in the  hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied  warranty  of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 
 * General Public License for more details.
 * 
 * For more  information, see  the file  COPYING provided with this
 * material.
 */
/*******************************************************************************
 * ModuleName  : ckpt                                                          
 * File        : clCkptApi.h
 *******************************************************************************/

/*******************************************************************************
 * Description :
 * File        : clCkptApi.h
*   This file contains Checkpoint service APIs defined by SAF
*
*
*****************************************************************************/

#ifndef _CL_CKPT_API_H_
#define _CL_CKPT_API_H_

# ifdef __cplusplus
extern "C" {
# endif

#include <clCommon.h>
#include <clIocApi.h>

/********************************
      C O N S T A N T S
********************************/

#define CL_CKPT_WR_ALL_REPLICAS        0X1

#define CL_CKPT_WR_ACTIVE_REPLICA      0X2

#define CL_CKPT_WR_ACTIVE_REPLICA_WEAK 0X4


#define CL_CKPT_CHECKPOINT_COLLOCATED  0X8

#define CL_CKPT_DISTRIBUTED           0X10

#define CL_CKPT_WR_ALL_SAFE            0X20

#define CL_CKPT_ALL_OPEN_ARE_REPLICAS  0x40

#define CL_CKPT_PEER_TO_PEER_REPLICA   0x80

#define CL_CKPT_PEER_TO_PEER_CACHE_DISABLE   0x100

#define CL_CKPT_CHECKPOINT_READ        0X1

#define CL_CKPT_CHECKPOINT_WRITE       0X2

#define CL_CKPT_CHECKPOINT_CREATE      0X4

#define CL_CKPT_DEFAULT_SECTION_ID   {0, NULL}

#define CL_CKPT_GENERATED_SECTION_ID {0, NULL}



typedef ClHandleT ClCkptSvcHdlT;

typedef ClHandleT ClCkptHdlT;

typedef ClHandleT ClCkptSecItrHdlT;

typedef ClUint32T  ClCkptCreationFlagsT;

typedef ClUint32T  ClCkptOpenFlagsT;
typedef ClUint32T  ClCkptSelectionObjT;

typedef struct {

    ClCkptCreationFlagsT   creationFlags;

    ClSizeT                checkpointSize;

    ClTimeT                retentionDuration;

    ClUint32T              maxSections;

    ClSizeT                maxSectionSize;

    ClSizeT                maxSectionIdSize;
} ClCkptCheckpointCreationAttributesT;

typedef struct {

    ClUint16T      idLen;

    ClUint8T       *id;

} ClCkptSectionIdT;

typedef struct {

    ClCkptSectionIdT          *sectionId;

    ClTimeT                expirationTime;
} ClCkptSectionCreationAttributesT;

typedef enum {

    CL_CKPT_SECTION_VALID = 1,

    CL_CKPT_SECTION_CORRUPTED = 2
} ClCkptSectionStateT;

typedef struct {

    ClCkptSectionIdT             sectionId;

    ClTimeT                   expirationTime;

    ClSizeT                   sectionSize;

    ClCkptSectionStateT          sectionState;

    ClTimeT                   lastUpdate;
} ClCkptSectionDescriptorT;

typedef enum {
    CL_CKPT_SECTIONS_FOREVER = 1,
    CL_CKPT_SECTIONS_LEQ_EXPIRATION_TIME = 2,
    CL_CKPT_SECTIONS_GEQ_EXPIRATION_TIME = 3,
    CL_CKPT_SECTIONS_CORRUPTED = 4,
    CL_CKPT_SECTIONS_ANY = 5
} ClCkptSectionsChosenT;

typedef struct {

    ClCkptSectionIdT      sectionId;

    ClPtrT                dataBuffer;

    ClSizeT               dataSize;

    ClOffsetT             dataOffset;

    ClSizeT               readSize;
} ClCkptIOVectorElementT;

typedef struct {

    ClCkptCheckpointCreationAttributesT   checkpointCreationAttributes;

    ClUint32T                        numberOfSections;

    ClUint32T                        memoryUsed;
} ClCkptCheckpointDescriptorT;

typedef ClRcT (*ClCkptNotificationCallbackT)( 
                        ClCkptHdlT              ckptHdl,
                        ClNameT                 *pName,
                        ClCkptIOVectorElementT  *pIOVector,
                        ClUint32T               numSections,
                        ClPtrT                  pCookie  );
typedef void (*ClCkptCheckpointOpenCallbackT)(
                        ClInvocationT     invocation,
                        ClCkptHdlT        checkpointHandle,
                        ClRcT             error);

typedef void (*ClCkptCheckpointSynchronizeCallbackT)(
                        ClInvocationT invocation,
                        ClRcT  error);

typedef struct {

    ClCkptCheckpointOpenCallbackT          checkpointOpenCallback;

    ClCkptCheckpointSynchronizeCallbackT   checkpointSynchronizeCallback;
} ClCkptCallbacksT;


extern ClRcT clCkptInitialize( CL_OUT ClCkptSvcHdlT            *ckptSvcHandle,  /* Checkpoint service handle */
                        CL_IN  const ClCkptCallbacksT   *callbacks,      /* Optional callbacks */
                        CL_INOUT ClVersionT             *version);       /* Version */




extern ClRcT clCkptFinalize( CL_IN ClCkptSvcHdlT ckptHandle);

extern ClRcT clCkptCheckpointOpen( CL_IN ClCkptSvcHdlT          ckptHandle,   /* Service handle */
                            CL_IN const ClNameT        *ckeckpointName, /* Name of the checkpoint */
                            CL_IN const ClCkptCheckpointCreationAttributesT *checkpointCreationAttributes,
                            CL_IN ClCkptOpenFlagsT       checkpointOpenFlags, /* Open flags */
                            CL_IN ClTimeT               timeout,             /* Time out */
                            CL_IN ClCkptHdlT             *checkpointHandle);  /* Return handle */



extern ClRcT clCkptCheckpointOpenAsync( CL_IN ClCkptSvcHdlT            ckptHandle,
                                 CL_IN ClInvocationT          invocation,
                                 CL_IN const ClNameT          *checkpointName,
                                 CL_IN const ClCkptCheckpointCreationAttributesT *checkpoiNtCreationAttributes,
                                 CL_IN ClCkptOpenFlagsT          checkpointOpenFlags);

extern ClRcT clCkptCheckpointClose(CL_IN ClCkptHdlT checkpointHandle);

extern ClRcT clCkptCheckpointDelete( CL_IN ClCkptSvcHdlT       ckptHandle,      /* checkpoint svc handle */
                              CL_IN const ClNameT     *checkpointName);

extern ClRcT clCkptCheckpointRetentionDurationSet( CL_IN ClCkptHdlT checkpointHandle,
                                            CL_IN ClTimeT retentionDuration);

extern ClRcT clCkptActiveReplicaSet(CL_IN ClCkptHdlT checkpointHandle);

extern ClRcT clCkptCheckpointStatusGet( CL_IN ClCkptHdlT                 checkpointHandle,
                                 CL_OUT ClCkptCheckpointDescriptorT *checkpointStatus);
extern ClRcT clCkptSectionCreate( CL_IN ClCkptHdlT         checkpointHandle,
                           CL_IN ClCkptSectionCreationAttributesT *sectionCreationAttributes,
                           CL_IN const ClUint8T   *initialData,
                           CL_IN ClSizeT         initialDataSize);


extern ClRcT clCkptSectionDelete( CL_IN ClCkptHdlT  checkpointHandle,
                           CL_IN const ClCkptSectionIdT     *sectionId);

extern ClRcT clCkptSectionExpirationTimeSet( CL_IN ClCkptHdlT                checkpointHandle,
                                      CL_IN const ClCkptSectionIdT*   sectionId,
                                      CL_IN ClTimeT                expirationTime);
extern ClRcT clCkptSectionIterationInitialize( CL_IN  ClCkptHdlT              checkpointHandle,
                                        CL_IN  ClCkptSectionsChosenT   sectionsChosen,
                                        CL_IN  ClTimeT              expirationTime,
                                        CL_OUT ClHandleT         *sectionIterationHandle);

extern ClRcT clCkptSectionIterationNext( CL_IN  ClHandleT   sectionIterationHandle,
                                  CL_OUT ClCkptSectionDescriptorT *sectionDescriptor);

extern ClRcT clCkptSectionIterationFinalize(CL_IN ClHandleT sectionIterationHandle);

extern ClRcT clCkptCheckpointWrite( CL_IN  ClCkptHdlT     checkpointHandle,
                             CL_IN  const ClCkptIOVectorElementT   *ioVector,
                             CL_IN  ClUint32T       numberOfElements,
                             CL_OUT ClUint32T      *erroneousVectorIndex);

extern ClRcT clCkptSectionOverwrite(CL_IN  ClCkptHdlT        checkpointHandle,
                              CL_IN const ClCkptSectionIdT    *sectionId,
                              CL_IN const void             *dataBuffer,
                              CL_IN ClSizeT                 dataSize);

extern ClRcT clCkptCheckpointRead( CL_IN ClCkptHdlT               checkpointHandle,
                            CL_INOUT ClCkptIOVectorElementT   *ioVector,
                            CL_IN ClUint32T              numberOfElements,
                            CL_OUT ClUint32T              *erroneousVectorIndex);

extern ClRcT clCkptCheckpointSynchronize( CL_IN ClCkptHdlT      ckeckpointHandle,
                                   CL_IN ClTimeT      timeout);
extern ClRcT clCkptCheckpointSynchronizeAsync( CL_IN ClCkptHdlT checkpointHandle,
                                        CL_IN ClInvocationT invocation);
extern ClRcT clCkptImmediateConsumptionRegister( CL_IN ClCkptHdlT checkpointHandle,
                                        CL_IN ClCkptNotificationCallbackT callback,
                                        CL_IN ClPtrT pCookie);

extern ClRcT clCkptSelectionObjectGet(CL_IN ClCkptSvcHdlT ckptHandle,
                                      CL_OUT ClSelectionObjectT *selectionObject);


extern ClRcT clCkptDispatch(CL_IN ClCkptSvcHdlT ckptHandle,
                            CL_IN ClDispatchFlagsT dispatchFlags);

#ifdef  __cplusplus
}
#endif

#endif  /* _CL_CKPT_API_H_*/