All Classes Files Functions Variables Pages
IpServices.idl
Go to the documentation of this file.
1 /**
2  * @file IpServices.idl
3  * @brief API for services administration
4  * @version 2
5  */
6 
7 #import <kerio/web/idl/SharedStructures.idl>
8 #import <common.idl>
9 
10 module webadmin {
11 
12 
13 /** service reference used in various policies */
15  kerio::web::KId id;
16  string name;
17  boolean isGroup;
18  boolean invalid;
19 };
20 
21 /**
22  * Different types of service's port definition
23  * names based on WAM's CompareOperator
24  */
25 enum PortComparator {
26  Any, ///< port not specified
27  Equal, ///< '=' - equal to
28  LessThan, ///< '<' - lower than
29  GreaterThan, ///< '>' - greater than
30  Range, ///< from/to values
31  List ///< list of values
32 };
33 
34 /**
35  * List of ports (port must be < 65536)
36  */
37 typedef sequence<long> PortList;
38 
39 /**
40  * Port - used to define condition for ports (i.e. one port, from/to range or greater/less than)
41  */
42 struct PortCondition {
43  PortComparator comparator; ///< does the list contains either single port (equal/greater/etc.), range or list of ports
44  PortList ports; /**< list of port numbers - meaning depends on comparator (see below) \n
45  - for comparator Equal, NotEqual, GreaterThan, LessThan => one port number for the condition \n
46  - for comparator Range => two port numbers defining the from/to range (inclusive) \n
47  - for comparator List => list of exact port numbers \n
48  - for comparator Any => list should be empty (if not, just ignore the values)
49  */
50 };
51 
52 const long ipProtoIcmp = 1;
53 const long ipProtoTcp = 6;
54 const long ipProtoUdp = 17;
55 const long ipProtoOther = 128;
56 const long ipProtoTcpUdp = 129;
57 
58 /**
59  * basic structure for Service's properties
60  */
61 struct IpService {
62  kerio::web::KId id; ///< never updated in store
63  kerio::web::StoreStatus status;
64  string name; ///< unique name for the service, max 23 chars
65  string description; ///< brief description of the service, max 63 chars, can be empty
66  long protocol; ///< ICMP 1, TCP - 6, UDP - 17, other - 128, TCP_UDP - 129
67  boolean group;
68 
69  /*@{ TCP, UDP, TCP_UDP */
70  PortCondition srcPort; ///< port(s) on client-side
71  PortCondition dstPort; ///< port(s) on server-side
72  /*@}*/
73 
74  /*@{ TCP, UDP */
75  string inspector; ///< name of Protocol Inspector, @see InspectorManager
76  /*@}*/
77 
78  /*@{ other */
79  long protoNumber; ///< 1-255
80  /*@}*/
81 
82  /*@{ ICMP */
83  kerio::web::StringList icmpTypes; ///< "any" or list of numbers
84  /*@}*/
85 
86  /*@{ group */
87  IdReferenceList members; ///< for group = true list of member IpService ids
88  /*@}*/
89 };
90 
91 typedef sequence<IpService> IpServiceList;
92 
93 interface IpServices {
94 
95  /**
96  * get the list of services
97  * @param list - list of services and it's details
98  * @param totalItems - count of all services on server (before the start/limit applied)
99  * @param query - conditions and limits. Included from weblib. Kerio Control engine implementation notes: \n
100  * - LIKE matches substring (second argument) in a string (first argument). There are no wildcards. \n
101  * - sort and match are case insensitive. \n
102  * - column alias (first operand): \n
103  * - "QUICKSEARCH" - requested operator applied as following: (name operator secondOperand ) || (description operator secondOperand)
104  * @throws kerio::web::ApiException \n
105  * -32001 Session expired. - "The user is not logged in." \n
106  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
107  */
108  void get(out IpServiceList list, out long totalItems, in kerio::web::SearchQuery query);
109 
110  /**
111  * add new services
112  * @param errors - list of errors \n
113  * 1001 Already exists. - "Service %1 already exists."
114  * @param result - list of IDs assigned to each item
115  * @param services - details for new services. field id is assigned by the manager to temporary value until apply() or reset().
116  * @throws kerio::web::ApiException \n
117  * -32001 Session expired. - "The user is not logged in." \n
118  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
119  */
120  void create(out kerio::web::ErrorList errors, out kerio::web::CreateResultList result, in IpServiceList services);
121 
122  /**
123  * update existing services
124  * @param errors - list of errors \n
125  * 1001 Already exists. - "Service %1 already exists."
126  * @param serviceIds - ids of services to be updated.
127  * @param details - details for update. Field "kerio::web::KId" is ignored. All other fields must be filled and they are written to all services specified by serviceIds.
128  * @throws kerio::web::ApiException \n
129  * -32001 Session expired. - "The user is not logged in." \n
130  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
131  */
132  void set(out kerio::web::ErrorList errors, in kerio::web::StringList serviceIds, in IpService details);
133 
134  /**
135  * remove services
136  * @param errors - list of errors TODO write particular values
137  * @param serviceIds - ids of services that should be removed
138  * @throws kerio::web::ApiException \n
139  * -32001 Session expired. - "The user is not logged in." \n
140  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
141  */
142  void remove(out kerio::web::ErrorList errors, in kerio::web::StringList serviceIds);
143 
144  /**
145  * write changes cached in manager to configuration
146  * @param errors - list of errors \n
147  * 8001 Invalid params. - "Unable to add/modify service %1, wrong parameters." \n
148  * 8002 Database error. - "Unable to add/modify service %1." \n
149  * 8002 Database error. - "Unable to delete the service."
150  * @throws kerio::web::ApiException \n
151  * -32001 Session expired. - "The user is not logged in." \n
152  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
153  */
154  void apply(out kerio::web::ErrorList errors);
155 
156  /**
157  * discard changes cached in manager
158  * @throws kerio::web::ApiException \n
159  * -32001 Session expired. - "The user is not logged in." \n
160  * 1004 Access denied. - "Insufficient rights to perform the requested operation."
161  */
162  void reset();
163 };
164 
165 }; //webadmin
PortComparator comparator
does the list contains either single port (equal/greater/etc.), range or list of ports ...
Definition: IpServices.idl:43
long protocol
ICMP 1, TCP - 6, UDP - 17, other - 128, TCP_UDP - 129.
Definition: IpServices.idl:66
Definition: IpServices.idl:14
kerio::web::KId id
never updated in store
Definition: IpServices.idl:62
Common Kerio Control structures, enums and types.
Definition: SharedStructures.idl:139
PortCondition dstPort
port(s) on server-side
Definition: IpServices.idl:71
long protoNumber
1-255
Definition: IpServices.idl:79
Definition: IpServices.idl:61
kerio::web::StringList icmpTypes
"any" or list of numbers
Definition: IpServices.idl:83
string inspector
name of Protocol Inspector,
Definition: IpServices.idl:75
string description
brief description of the service, max 63 chars, can be empty
Definition: IpServices.idl:65
Definition: IpServices.idl:93
PortCondition srcPort
port(s) on client-side
Definition: IpServices.idl:70
Definition: IpServices.idl:42
string name
unique name for the service, max 23 chars
Definition: IpServices.idl:64
Definition: Accounting.idl:11
IdReferenceList members
for group = true list of member IpService ids
Definition: IpServices.idl:87
PortList ports
Definition: IpServices.idl:44