SharedStructures.idl

Go to the documentation of this file.

/**
 * @file   SharedStructures.idl
 * @brief  Shared data structures without an interface
 *
 * @author Dusan Juhas
 *
 * Copyright © 2017 Kerio Technologies s.r.o.
 */

module kerio {
module web {

/**
 * Type for lists of strings.
 */
typedef sequence<string> StringList;

/**
 * Type for lists of integers.
 */
typedef sequence<long> IntegerList;

/**
 * Name-value pair
 * Note: all fields must be assigned if used in set methods
 */
struct NamedValue {
   string name;
   string value;
};

/**
 * List of name-value pairs
 */
typedef sequence<NamedValue> NamedValueList;

/**
 * Name-multivalue pair
 * Note: all fields must be assigned if used in set methods
 */
struct NamedMultiValue {
   string name;
   StringList value;
};

/**
 * List of name-multivalue pairs
 */
typedef sequence<NamedMultiValue> NamedMultiValueList;

/**
 * global object identification
 */
typedef string KId;
/**
 * list of global object identifiers
 */
typedef sequence<KId> KIdList;

/**
 * Sorting Direction
 */
enum SortDirection {
   Asc, ///< ascending order
   Desc ///< descending order
};

/**
 * Simple Query Operator
 */
enum CompareOperator {
   Eq,         ///< '='  - equal
   NotEq,      ///< '<>' - not equal
   LessThan,   ///< '<'  - lower that
   GreaterThan,///< '>'  - greater that
   LessEq,     ///< '<=' - lower or equal
   GreaterEq,  ///< '>=' - greater or equal
   Like     ///< contains substring, % is wild character
};

/**
 * Compound Operator
 */
enum LogicalOperator {
   Or,
   And
};

/**
 * A Part of a Condition
 */
struct SubCondition {
       string               fieldName;           ///< left side of condition
       CompareOperator      comparator;                ///< middle of condition
       string               value;        ///< right side of condition
};

/**
 * A Complete Condition
 */
typedef sequence<SubCondition> SubConditionList;

/**
 * Sorting Order
 */
struct SortOrder {
   string         columnName;
   SortDirection  direction;
   boolean        caseSensitive;
};

/**
 * List of Sorting Orders
 */
typedef sequence<SortOrder> SortOrderList;

/**
 * General Query for Searching
 *
 *
 * Query substitution (quicksearch):
 *
 * SearchQuery doesn't support complex queries, only queries
 * with all AND operators (or all OR operators) are supported.
 * Combination of AND and OR is not allowed. This limitation is for special cases solved by using
 * substitution of complicated query-part by simple condition.
 *
 * Only the quicksearch is currently implemented and only in "Users::get()" method.
 *
 * Behavior of quicksearch in Users::get():
 *
 * QUICKSEACH    = "x"   is equal to:   (loginName    = "x")  OR (fullName    = "x")
 *
 * QUICKSEACH LIKE "x*"  is equal to:   (loginName LIKE "x*") OR (fullName LIKE "x*")
 *
 * QUICKSEACH   <> "x"   is equal to:   (loginName   <> "x") AND (fullName   <> "x")
 *
 */
struct SearchQuery {
   StringList        fields;     ///< empty = give me all fields, applicable constants: ADD_USERS, LIST_USERS
   SubConditionList  conditions; ///< empty = without condition
   LogicalOperator      combining;  ///< the list of conditions can be either combined by 'ORs' or 'ANDs'
   long           start;      ///< how many items to skip before filling a result list (0 means skip none)
   long           limit;      ///< how many items to put to a result list (if there are enough items); applicable constant: Unlimited
   SortOrderList     orderBy;
};

/**
 * Message can contain replacement marks:  { "User %1 cannot be deleted.", ["jsmith"], 1 }
 */
struct LocalizableMessage {
   string message;                    ///< text with placeholders %1, %2, etc., e.g. "User %1 cannot be deleted."
   StringList positionalParameters; ///< additional strings to replace the placeholders in message (first string replaces %1 etc.)
   long plurality;                    ///< count of items, used to distinguish among singular/paucal/plural; 1 for messages with no counted items
};

typedef sequence<LocalizableMessage> LocalizableMessageList;

/**
 * error structure to be used when manipulating with globally addressable list items
 */
struct ManipulationError {
   KId               id;         ///< entity KId, can be user, group, alias, ML...
   LocalizableMessage   errorMessage;
};

typedef sequence<ManipulationError> ManipulationErrorList;

/**
 * A kind of restriction
 */
enum RestrictionKind {
   Regex,                  ///< regular expression
   ByteLength,             ///< maximal length in Bytes
   ForbiddenNameList,         ///< list of denied exact names due to filesystem or KMS store
   ForbiddenPrefixList,    ///< list of denied preffixes due to filesystem or KMS store
   ForbiddenSuffixList,    ///< list of denied suffixes due to filesystem or KMS store
   ForbiddenCharacterList     ///< list of denied characters
};

/**
 * Item of the Entity; used in restrictions
 */
enum ItemName {
   Name,       ///< Entity Name
   Description,   ///< Entity Description
   Email,         ///< Entity Email Address
   FullName,      ///< Entity Full Name
   TimeItem,      ///< Entity Time - it cannot be simply Time because of C++ conflict - see bug 34684 comment #3
   DateItem,      ///< Entity Date - I expect same problem with Date as with Time
   DomainName     ///< differs from name (eg. cannot contains underscore)
};

/**
 * Units used for handling large values of bytes.
 * See also userinfo.idl: enum UserValueUnits.
 */
enum ByteUnits {
    Bytes,
    KiloBytes,
    MegaBytes,
    GigaBytes,
    TeraBytes,
    PetaBytes
};

/**
 * Stores size of very large values of bytes e.g. for user quota
 * Note: all fields must be assigned if used in set methods
 */
struct ByteValueWithUnits {
   long       value;
   ByteUnits  units;
};

/**
 * Settings of size limit
 * Note: all fields must be assigned if used in set methods
 */
struct SizeLimit {
   boolean              isActive;
   ByteValueWithUnits   limit;
};

/**
 * Result of the add operation
 */
struct AddResult {
   KId id;                       ///< purposely not id - loginName is shown
   boolean  success;             ///< was operation successful? if yes so id is new id for this item else errorMessage tells why it failed
   LocalizableMessage errorMessage; ///< contains number of recovered user messages or error message
};

/**
 * list of add operation results
 */
typedef sequence<AddResult> AddResultList;

typedef string IpAddress;
typedef sequence<IpAddress> IpAddressList;

/**
 * Status of entry in persistent manager
 */
enum StoreStatus {
   StoreStatusClean,        ///< already present in configuration store
   StoreStatusModified,     ///< update waiting for apply()
   StoreStatusNew           ///< added to manager but not synced to configuration store
};

/**
 * When using start and limit to only get a part of all results
 * (e.g. only 20 users, skipping the first 40 users),
 * use this special limit value for unlimited count
 * (of course the service still respects the value of start).
 *
 * Note that each service is allowed to use its safety limit
 * (such as 50,000) to prevent useless overload.
 * The limits are documented per-service or per-method.
 *
 * Implementation note: Some source code transformations may lead to signed long, i.e. 4294967295.
 * But the correct value is -1.
 */
const long Unlimited = -1;

/**
 * Date and Time - should be used instead of time_t, where time zones can affect time interpretation
 * Note: all fields must be assigned if used in set methods
 */
struct Time {
   long hour;  ///< 0-23
   long min;   ///< 0-59
};

/**
 *
 * Note: all fields must be assigned if used in set methods
 */
struct Date {
   long year;
   long month;    ///< 0-11
   long day;      ///< 1-31 max day is limited by month
};

/**
 * A string that can be switched on/off. String is meaningful only if switched on.
 * Note: all fields must be assigned if used in set methods
 */
struct OptionalString {
   boolean enabled;
   string value;
};

/**
 *
 * Note: all fields must be assigned if used in set methods
 */
struct OptionalLong {
   boolean enabled;
   long value;
};

/**
 * IP Address Group / Time Range / ... that can be switched on/off
 * Note: all fields must be assigned if used in set methods
 */
struct OptionalEntity {
   boolean enabled;
   KId      id;         ///< global identifier
   string   name;
};

/**
 * Message can contain replacement marks:  { "User %1 cannot be deleted.", ["jsmith"], 1 }.
 * This is the parameters structure.
 */
struct LocalizableMessageParameters {
   StringList positionalParameters;  ///< additional strings to replace the placeholders in message (first string replaces %1 etc.)
   long       plurality;             ///< count of items, used to distinguish among singular/paucal/plural; 1 for messages with no counted items
};

/**
 * Error details regarding a particular item, e.g. one of users that could not be updated or removed.
 */
struct Error {
   long                         inputIndex;        ///< 0-based index to input array, e.g. 3 means that the relates to the 4th element of the input parameter array
   long                         code;              ///< -32767..-1 (JSON-RPC) or 1..32767 (application)
   string                       message;           ///< text with placeholders %1, %2, etc., e.g. "User %1 cannot be deleted."
   LocalizableMessageParameters messageParameters; ///< strings to replace placeholders in message, and message plurality.
};
typedef sequence<Error> ErrorList;

exception ApiException {
 string message;         ///< text with placeholders %1, %2
 long code;              ///< -32767..-1 (JSON-RPC) or 1..32767 (application)
 LocalizableMessageParameters messageParameters; ///< strings to replace placeholders in message, and message plurality.
};

/**
 * important information about download
 */
struct Download {
   string url; ///< download url
   string name;   ///< filename
   long length;   ///< file size in bytes
};

/**
 * Details about a particular item created.
 */
struct CreateResult {
    long inputIndex;    ///< 0-based index to input array, e.g. 3 means that the relates to the 4th element of the input parameter array
    KId  id;            ///< ID of created item.
};

typedef sequence<CreateResult> CreateResultList;

/**
 * Type for date/time representation
 */
typedef long DateTimeStamp;

/**
 * Describes client (third-party) application or script which uses the Administration API.
 */
struct ApiApplication {
   string name;       ///< E.g. "Simple server monitor"
   string vendor;     ///< E.g. "MyScript Ltd."
   string version;    ///< E.g. "1.0.0 beta 1"
};

/**
 * Credentials contains userName and password
 */
struct Credentials {
    string userName;     ///< UserName
    string password;     ///< Password
};

}; // module web
}; // module kerio