SecExperiment/SecExperimentPriv.h

   1 //
   2 //  SecExperimentPriv.h
   3 //  Security
   4 //
   5
   6 #ifndef SecExperiment_h
   7 #define SecExperiment_h
   8
   9 #include <Security/SecProtocolObject.h>
  10
  11 #ifndef SEC_EXP_OBJECT_IMPL
  12 SEC_OBJECT_DECL(sec_experiment);
  13 #endif // !SEC_EXP_OBJECT_IMPL
  14
  15 SEC_ASSUME_NONNULL_BEGIN
  16
  17 extern const char *kSecExperimentTLSMobileAssetConfig;
  18 extern const char *kSecExperimentDefaultsDomain;
  19
  20 /*!
  21  * @block sec_experiment_run_block_t
  22  *
  23  * @abstract A block to execute an experiment with a loggable identifier
  24  *     and configuration. `identifier` will be uniquely associated with
  25  *     `experiment_config` and should be used when measuring data.
  26  *
  27  * @param identifier
  28  *     Identifier for the experiment.
  29  *
  30  * @param experiment_config
  31  *     Configuration of this experiment.
  32  *
  33  * @return True if the experiment ran successfully, and false otherwise.
  34  */
  35 typedef bool (^sec_experiment_run_block_t)(const char *identifier, xpc_object_t experiment_config);
  36
  37 /*!
  38  * @function sec_experiment_run
  39  *
  40  * @abstract
  41  *      Asynchronously run an experiment.
  42  *
  43  * @param experiment_name
  44  *      Name of the experiment to run.
  45  *
  46  * @param queue
  47  *      Queue on which to run the experiment.
  48  *
  49  * @param run_block
  50  *      A `sec_experiment_run_block_t` block upon which to execute the given experiment.
  51  */
  52 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  53 bool
  54 sec_experiment_run(const char *experiment_name, dispatch_queue_t queue, sec_experiment_run_block_t run_block);
  55
  56 /*!
  57  * @function sec_experiment_create
  58  *
  59  * @abstract
  60  *      Create an ARC-able `sec_experiment_t` instance
  61  *
  62  * @param experiment_name
  63  *      Name of the experiment.
  64  *
  65  * @return a `sec_experiment_t` instance.
  66  */
  67 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  68 SEC_RETURNS_RETAINED _Nullable sec_experiment_t
  69 sec_experiment_create(const char *experiment_name);
  70
  71 /*!
  72  * @function sec_experiment_set_sampling_disabled
  73  *
  74  * @abstract
  75  *      Set a flag to disable experiment sampling.
  76  *      This function should only be used for testing purposes.
  77  *
  78  * @param experiment
  79  *      A `sec_experiment_t` instance.
  80  *
  81  * @param sampling_disabled
  82  *      A flag indicating if sampling should be disabled.
  83  */
  84 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
  85 void
  86 sec_experiment_set_sampling_disabled(sec_experiment_t experiment, bool sampling_disabled);
  87
  88 /*!
  89  * @function sec_experiment_copy_configuration
  90  *
  91  * @abstract
  92  *      Returns the configuration dictionary associated with the given experiment.
  93  *
  94  * @param experiment
  95  *      A valid `sec_experiment_t` instance.
  96  *
  97  * @return  xpc_object_t containing asset bundle, if client is not part of the experiment return NULL
  98  */
  99 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 100 SEC_RETURNS_RETAINED _Nullable xpc_object_t
 101 sec_experiment_copy_configuration(sec_experiment_t experiment);
 102
 103 /*!
 104  * @function sec_experiment_get_identifier
 105  *
 106  * @abstract
 107  *      Returns a loggable identifier for the given experiment.
 108  *
 109  * @param experiment
 110  *      A valid `sec_experiment_t` instance.
 111  *
 112  * @return A NULL-terminated, loggable experiment identifier.
 113  */
 114 API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0))
 115 const char * _Nullable
 116 sec_experiment_get_identifier(sec_experiment_t experiment);
 117
 118 SEC_ASSUME_NONNULL_END
 119
 120 #endif // SecExperiment_h