DMTrial.h

//
//  DMTrial.h
//  DevMateActivations
//
//  Copyright (c) 2013-2014 MacPaw Inc. All rights reserved.
//

#ifndef __DevMateActivations__DMTrial__
#define __DevMateActivations__DMTrial__

#include <CoreFoundation/CoreFoundation.h>

CF_EXTERN_C_BEGIN

typedef CF_ENUM(CFIndex, DMTrialState)
{
    kDMTrialStateUndefined = 0,
    kDMTrialStateValid,
    kDMTrialStateInvalid
};

enum
{
    kDMTrialTypeManual = 0,
    kDMTrialTypeTime,
    
    kDMTrialTypeDefault = kDMTrialTypeManual
};
typedef CFIndex DMTrialType;

typedef CF_ENUM(CFIndex, DMTrialArea)
{
    kDMTrialAreaPerOneUser = 0,
    kDMTrialAreaForAllUsers, // to support in sandboxed app, add com.apple.security.temporary-exception.files.absolute-path.read-write with "/Users/Shared/" to your entitlements file
    
    kDMTrialAreaDefault = kDMTrialAreaPerOneUser
};

/*! @brief Callback block for getting MAX trial value that application supports
    @param context Parameter from \p DMTrialCallbacks structure.
    @return MAX trial value that application supports.
 */
typedef CFIndex (^DMTrialGetEndValueBlock)(void *context);

/*! @brief Callback block for changing current trial value.
    @param currentTialValue Trial value that is currently saved for application.
    @param changeValue      Value from \p DMTrialChangeValue function call.
    @param context          Parameter from \p DMTrialCallbacks structure.
    @return New changed trial value that should be saved for application.
 */
typedef CFIndex (^DMTrialChangeValueBlock)(CFIndex currentTrialValue, CFIndex changeValue, void *context);

/*! @brief Callback block for informing about application trial did end (became invalid).
    @param context Parameter from \p DMTrialCallbacks structure.
 */
typedef void (^DMTrialDidEndBlock)(void *context);

/*! @brief Callback block for cleaning up.
    @param context Parameter from \p DMTrialCallbacks structure.
 */
typedef void (^DMTrialFinalizeBlock)(void *context);


/*! @brief Structure of callback parameters used for informing about different trial changes.
    @discussion Be informed that some of structure parameters are required and can not be \p NULL.
    @discussion All callback blocks will be copied with \p Block_copy() by trial while initializing and released with \p Block_release() later.
 */
typedef struct __DMTrialCallbacks
{
    __unsafe_unretained DMTrialGetEndValueBlock getEndValue; // required
    __unsafe_unretained DMTrialChangeValueBlock changeValue; // required
    __unsafe_unretained DMTrialDidEndBlock didEndTrial; // optional
    __unsafe_unretained DMTrialFinalizeBlock finalize; // optional
    void *context; // optional
} DMTrialCallbacks;

//! Notification name for cases when application trial did end (became invalid). Notification object is \p NULL.
CF_EXPORT const CFStringRef kDMTrialDidEndNotification;

/*! @brief Function for initializing trial for application.
    @param trialType        Type of application trial. You can use your own types.
    @param trialArea        Trial area. See \p DMTrialArea enum for details.
    @param callbacks        Structure of callbacks.
    @param shouldContinue   \p true in case when trial should use previously saved value as start value. \p false in case when trial should invalidate all previous data and start new trial count.
    @return Success result. \p true in case when trial was initialized successfully.
 */
CF_EXPORT Boolean DMTrialInitialize(DMTrialType trialType, DMTrialArea trialArea, DMTrialCallbacks callbacks, Boolean shouldContinue);

//! Returns trial type. Undefined behavior for uninitialized trial.
CF_EXPORT DMTrialType DMTrialGetType(void);

//! Returns trial area. Undefined behavior for uninitialized trial.
CF_EXPORT DMTrialArea DMTrialGetArea(void);

//! Returns trial state. Undefined behavior for uninitialized trial.
CF_EXPORT DMTrialState DMTrialGetState(void);

//! Returns \p true in case trial has ever been initialized, \p false otherwise.
CF_EXPORT Boolean DMTrialHasHistory(void);

/*! @brief Returns current trial value.
    @discussion Trial value always will be in range of [0, MAX_TRIAL_VALUE] for valid trial where MAX_TRIAL_VALUE is a result of \p getEndValue callback block.
    @discussion Will return LONG_MAX for invalid trial.
 */
CF_EXPORT CFIndex DMTrialGetCurrentValue(void);

/*! @brief Function to change current trial value manually.
    @discussion Input value will be one of the arguments of callback block \p changeValue.
    @param changeValue Delta value for incrementing current trial value. For simple case formula is \p newTrialValue=\p currentTrialValue+\p changeValue.
 */
CF_EXPORT void DMTrialChangeValue(CFIndex changeValue);

/*! @brief Function to invalidate application trial. Does nothing for already invalid trial.
 */
CF_EXPORT void DMTrialInvalidate(void);

//========================== Time trial functions ==========================//

#define kDMTrialMinute   60
#define kDMTrialHour     3600
#define kDMTrialDay      86400
#define kDMTrialWeek     604800      /* 7 days */
#define kDMTrialMonth    2592000     /* 30 days */
#define kDMTrialYear     31536000    /* 365 days */

/*! @brief Function to initialize time trial.
    @discussion Trial will be valid for \p timeInterval seconds and then will send notification about invalidation. Trial time will be counted starting from the first initialization (even when application is not running).
    @param trialArea        Trial area. See \p DMTrialArea for more details.
    @param timeInterval     Time interval in seconds (trial MAX time).
    @param shouldContinue   \p false if you want to restart time trial, \p true otherwise.
    @return Success result.
 */
CF_EXPORT Boolean DMTimeTrialInitialize(DMTrialArea trialArea, CFTimeInterval timeInterval, Boolean shouldContinue);

CF_EXTERN_C_END

#endif // __DevMateActivations__DMTrial__