Dhcp.idl

Go to the documentation of this file.

/**
 * @file     Dhcp.idl
 * @brief    API for DHCP
 * @version  3
 */
 
#import <common.idl>
 
module webadmin {
 
struct DhcpExclusion {
  string description;
  kerio::web::IpAddress ipStart;
  kerio::web::IpAddress ipEnd;
};
 
typedef sequence<DhcpExclusion>  DhcpExclusionList;
 
enum DhcpOptionType {
  DhcpBool,
  DhcpInt8,
  DhcpInt16,
  DhcpInt32,
  DhcpIpAddr,
  DhcpString,
  DhcpHex,
  DhcpTimeSigned,
  DhcpTimeUnsigned,
  DhcpInt8List,
  DhcpInt16List,
  DhcpInt32List,
  DhcpIpAddrList,
  DhcpIpPairList,
  DhcpIpMaskList,
  DhcpIpMaskIpList
};

typedef sequence<kerio::web::IpAddressList>  IpListList;

struct DhcpOption {
   DhcpOptionType type;
   long optionId;
   string name;

   /**
    * @note: Value format:  \n
    *  DHOTIpAddr - address in dot notation (192.168.0.12) \n
    *  DHOTHex - pairs of characters 0-9, a-f (12ef980ad8) \n
    *  DHOTTimexxx - number of seconds (3600) (negative only for DHOTTimeSigned) \n
    *  xxxList - values separated by ; (xxx;xx;x;xxxx) \n
    *  DHOTBool - "0" / "1"
    */       
   /*@{ DHOTBool, DHOTInt8, DHOTInt16, DHOTInt32, DHOTIpAddr, DHOTString, DHOTHex
   , DHOTTimeSigned, DHOTTimeUnsigned, DHOTInt8List, DHOTInt16List, DHOTInt32List, DHOTIpAddrList,*/     
   string value;
   /*@}*/ 
    
   /*@{ DHOTIpPairList, DHOTIpMaskList, DHOTIpMaskIpList */  
   IpListList ipListList; 
   /*@}*/ 
};
 
typedef sequence<DhcpOption>  DhcpOptionList;
 
struct DhcpScope {
  kerio::web::KId id;
  kerio::web::StoreStatus status;

  boolean enabled;
  string name;
  kerio::web::IpAddress ipStart;
  kerio::web::IpAddress ipEnd;
  kerio::web::IpAddress ipMask;

  DhcpExclusionList exclusions;

  DhcpOptionList options;
};
 
typedef sequence<DhcpScope>  DhcpScopeList;

enum DhcpLeaseType {
  DhcpTypeReservation,
  DhcpTypeLease
};

struct DhcpLease {
  kerio::web::KId id;
  kerio::web::KId leaseId; /// for internal purposes
  
  kerio::web::KId scopeId;
  kerio::web::StoreStatus status;

  /** do not change in gui */
  DhcpLeaseType type;
  boolean leased;
  boolean isRas;
  string cardManufacturer;
  
  kerio::web::IpAddress ipAddress;
  string name;
  boolean macDefined;
  string macAddress;
  string hostName;
  string userName;
  
  kerio::web::Date expirationDate;      ///< @see SharedStructures.idl shared in lib
  kerio::web::Time expirationTime;      ///< @see SharedStructures.idl shared in lib

  kerio::web::Date requestDate;      ///< @see SharedStructures.idl shared in lib
  kerio::web::Time requestTime;      ///< @see SharedStructures.idl shared in lib
  
  DhcpOptionList options;
};

typedef sequence<DhcpLease>  DhcpLeaseList;

enum DhcpModeType {
  DhcpAutomatic,
  DhcpManual
};

struct DhcpConfig {
   boolean enabled;
};

struct DhcpMode {
   DhcpModeType type;
};

interface Dhcp {

   /**
    * ** SCOPES PART **
    */

   /**
    * get the list of scopes
    * @param  list - list of scopes and it's details
    * @param  totalItems - count of all scopes on server (before the start/limit applied)
    * @param  query - conditions and limits
    * @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 DhcpScopeList list, out long totalItems, in kerio::web::SearchQuery query);

   /**
    * add new scope
    * @param  errors - list of errors \n
    *          1001  Already exists.  - "Unable to add/modify DHCP scope %1. Scope is a subnet of another scope." \n
    *          1001  Already exists.  - "Unable to add/modify DHCP scope %1. Another scope is a subnet of this scope." \n
    *          1001  Already exists.  - "Unable to add/modify DHCP scope %1. Scope on the same subnet is already defined." \n
    *          8001  Invalid params.  - "Unable to add/modify DHCP scope %1. First address and Last address are from different networks."
    * @param result - list of IDs assigned to each item   
    * @param scopes - details for new scopes. 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 DhcpScopeList scopes);

   /**
    * update existing scope
    * @param  errors - list of errors \n
    *          1001  Already exists.  - "Unable to add/modify DHCP scope %1. Scope is a subnet of another scope." \n
    *          1001  Already exists.  - "Unable to add/modify DHCP scope %1. Another scope is a subnet of this scope." \n
    *          1001  Already exists.  - "Unable to add/modify DHCP scope %1. Scope on the same subnet is already defined." \n
    *          8001  Invalid params.  - "Unable to add/modify DHCP scope %1. First address and Last address are from different networks." 
    * @param scopeIds - ids of scopes 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 scopes specified by scopeIds.   
    * @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 scopeIds, in DhcpScope details);

   /**
    * remove scope
    * @param errors - list of errors       
    * @param scopeIds - ids of scopes 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 scopeIds);

   /**
    * get generated scope information for interface
    * @param details - configuration for given ifaceId - can be passed to create method
    * @param ifaceId - id of interface, for which the template will be created
    * @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 getInterfaceTemplate(out DhcpScope details, in kerio::web::KId ifaceId);   
   
   /**
    * ** LEASE & RESERVATION PART **
    */

   /**
    * get the list of leases
    * @param  list - list of leases/reservations and it's details
    * @param  totalItems - count of all leases/reservations on server (before the start/limit applied)
    * @param  query - conditions and limits
    * @param  scopeIds - list of scope Ids, where leases should be included (empty for all scopes)
    * @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 getLeases(out DhcpLeaseList list, out long totalItems, in kerio::web::SearchQuery query, in kerio::web::KIdList scopeIds);

   /**
    * add new reservation
    * @param  errors - list of errors \n
    *          1001  Already exists.  - "DHCP reservation for %1 already exists."
    * @param result - list of IDs assigned to each item    
    * @param leases - details for new reservations. 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 createLeases(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in DhcpLeaseList leases);

   /**
    * update existing leases
    * @param  errors - list of errors \n
    *          1001  Already exists.  - "DHCP reservation for %1 already exists."  
    * @param leaseIds - ids of reservations 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 scopes specified by scopeIds.   
    * @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 setLeases(out kerio::web::ErrorList errors, in kerio::web::StringList leaseIds, in DhcpLease details);

   /**
    * remove leases
    * @param errors - list of errors       
    * @param leaseIds - ids of leases/reservations 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 removeLeases(out kerio::web::ErrorList errors, in kerio::web::StringList leaseIds);

   /**
    * ** COMMON PART **
    */

   /**
    * read Dhcp mode (not part of persistent manager, returns actual state)
    * @param  mode - result       
    * @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 getMode(out DhcpMode mode);
   
   /**
    * stores Dhcp mode (not part of persistent manager, changes mode immediately)
    * @param  mode - new value
    * @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 setMode(in DhcpMode mode);
   
   /**
    * read Dhcp configuration (not part of persistent manager, returns actual state)
    * @param  config - configuration values
    * @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 getConfig(out DhcpConfig config);
   
   /**
    * stores Dhcp configuration (not part of persistent manager, changes settings immediately)
    * @param  config - configuration values
    * @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 setConfig(in DhcpConfig config);

   /**
    * get list of all options
    * @param  options - list of all options
    * @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 getOptionList(out DhcpOptionList options); 

   /**
    * Returns count of declined leases in all scopes, defined by scopeIDs param
    * @param  count - count of declined leases
    * @param  scopeIds - list of scope IDs or empty for all scopes
    * @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 getDeclinedLeases(out long count, in kerio::web::KIdList scopeIds);

   /**
    * Removes declined leases defined by scopeIDs param from engine
    * @param  scopeIds - list of scope IDs or empty for all scopes
    * @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 removeDeclinedLeases(in kerio::web::KIdList scopeIds);

   /**
    * write changes cached in manager to configuration
    * @param  errors - list of errors \n
    *          8001  Invalid params.  - "Unable to add/modify DHCP reservation %1, wrong parameters." \n
    *          8001  Invalid params.  - "Unable to add/modify DHCP scope %1. Wrong address scope or mask." \n
    *          8002  Database error.  - "Unable to add/modify DHCP reservation %1." \n
    *          8002  Database error.  - "Unable to delete the DHCP reservation." \n
    *          8002  Database error.  - "Unable to add/modify DHCP scope %1." \n
    *          8002  Database error.  - "Unable to delete the DHCP scope." 
    * @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();

};

}; //webadmin