UrlGroups.idl

Go to the documentation of this file.

/**
 * @file     UrlGroups.idl
 * @brief    API for Url groups
 * @version  2
 */

#import <kerio/web/idl/SharedStructures.idl>

module webadmin {
 
enum UrlEntryType {
   Url,
   UrlChildGroup
};

struct UrlGroup {
   kerio::web::KId id;
   string name;
};

struct UrlEntry {
   kerio::web::KId id;
   kerio::web::KId groupId;
   kerio::web::KId sharedId;  ///< read-only; filled when the item is shared in MyKerio
   string groupName;
   string description;

   UrlEntryType type;
   boolean enabled;
   kerio::web::StoreStatus status;

   /*@{ url */
   string url;
   boolean isRegex;
   /*@}*/

   /*@{ group */
   kerio::web::KId childGroupId;
   string childGroupName; /**< ignored upon update */
   /*@}*/
};

typedef sequence<UrlEntry>  UrlEntryList;
typedef sequence<UrlGroup>  UrlGroupList;

interface UrlGroups {

   /**
    * get the list of Url groups
    * @param  list - list of groups and it's details
    * @param  totalItems - count of all groups on server (before the start/limit applied)
    * @param  query - conditions and limits. Included from weblib. Kerio Control engine implementation notes: \n
    *  - LIKE matches substring (second argument) in a string (first argument). There are no wildcards. \n
    *  - sort and match are case insensitive. \n
    *  - column alias (first operand): \n
    *    - TODO: "QUICKSEARCH" - requested operator applied as following: (name operator secondOperand ) || (description operator secondOperand)
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */ 
   void get(out UrlEntryList list, out long totalItems, in kerio::web::SearchQuery query);

   /**
    * add new groups
    * @param  errors - list of errors \n
    *          1001  Already exists.  - "The URL group already exists."
    * @param result - list of IDs assigned to each item    
    * @param groups - details for new groups. field id is assigned by the manager to temporary value until apply() or reset().
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */ 
   void create(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in UrlEntryList groups);

   /**
    * update existing groups
    * @param  errors - list of errors \n
    *          1001  Already exists.  - "The URL group already exists." 
    * @param groupIds - ids of groups to be updated.
    * @param details - details for update. Field "kerio::web::KId" is ignored. All other fields must be filled and they are written to all groups specified by groupIds.
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */ 
   void set(out kerio::web::ErrorList errors, in kerio::web::StringList groupIds, in UrlEntry details);

   /**
    * remove groups
    * @param  errors - list of errors TODO write particular errors
    * @param groupIds - ids of groups that should be removed
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */ 
   void remove(out kerio::web::ErrorList errors, in kerio::web::StringList groupIds);

   /**
    * write changes cached in manager to configuration
    * @param  errors - list of errors \n
    *          8001  Invalid params.  - "Unable to add/modify URL group %1, wrong parameters." \n
    *          8002  Database error.  - "Unable to add/modify URL group %1." \n
    *          8002  Database error.  - "Unable to delete URL group." \n
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */ 
   void apply(out kerio::web::ErrorList errors);

   /**
    * discard changes cached in manager
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */ 
   void reset();

   /**
    * get the list of groups, sorted in asc order
    * @throws kerio::web::ApiException \n
    *         -32001 Session expired. - "The user is not logged in." \n
    *          1004  Access denied.   - "Insufficient rights to perform the requested operation."
    */ 
   void getGroupList(out UrlGroupList groups);
};

}; //webadmin