sample, sample, kPMSample — Description for sampling.


sample structure { source, initial delay, frequency, window, limit, criteria, ... };
source : string, choice, default
initial delay : integer, default, optional, range 0..n
frequency : integer, default, optional, range 0..n
window : integer, default, optional, range 1..n
limit : integer, optional, range 1..n
criteria : array of sample criterion structures, length 1..n, optional, unique


Description for sampling.

sample describes the constraints and criteria for sampling the environment and determining a result. sample provides a generic solution to a class of common situations that require near constant monitoring of external events.


source. Source of samples.

source is a string. If source is omitted, the default execute external is used. source must be execute external, kPMSampleSource_ExecuteExternal.

initial delay. Delay before sampling begins in seconds.

initial delay is an integer. If initial delay is omitted, the default 0 is used. initial delay is optional. initial delay must be more than or equal to 0.

frequency. Frequency of sampling in seconds.

frequency is an integer. If frequency is omitted, the default 30 is used. frequency is optional. frequency must be more than or equal to 0.

window. Sample window to evaluate.

The number of historic samples to use when determining if the criteria has been met. The window represents a collection of the latest samples gathered. As samples leave the window they are released and will not be used in any future evaluations.

No evaluation will occur until enough samples have been collected to fill the window.

window is an integer. If window is omitted, the default 1 is used. window is optional. window must be more than or equal to 1.

limit. Seconds after sampling begins that it is stopped.

If the sampling has not reached a result and limit's duration has passed since sampling begun, stop the sampling. Limit provides a time constraint on the sampling process.

limit is an integer. limit is optional. limit must be more than or equal to 1.

criteria. Criteria to evaluate gathered samples with.

criteria is an array of sample criterion structures. criteria is optional. criteria must be 1 items or more. Each item in criteria must be unique.