Raritan / Server Technology Xerus™ PDU JSON-RPC API
DataPushService.idl
1 /* SPDX-License-Identifier: BSD-3-Clause */
2 /*
3  * Copyright 2014 Raritan Inc. All rights reserved.
4  */
5 
6 #include <UserEvent.idl>
7 
8 /** Event interface */
9 module event {
10 
11  /** Data push service configuration interface */
12  interface DataPushService {
13 
14  /**
15  * Data Push Entry Types
16  */
17  enumeration EntryType {
18  SENSORLIST, ///< Sensor values for a set of sensors
19  SENSORLOG, ///< Sensor log
20  AMSLIST, ///< Asset Management information for a set of AMS strips
21  AMSLOG, ///< Asset Management log
22  AUDITLOG ///< Audit log
23  };
24 
25  /** Error codes */
26  constant int ERR_NO_SUCH_ID = 1; ///< No such ID
27  constant int ERR_INVALID_PARAMS = 2; ///< Invalid parameters
28  constant int ERR_MAX_ENTRIES_REACHED = 3; ///< Maximum number of entries reached
29 
30  /**
31  * Data Push Entry Settings
32  */
33  structure EntrySettings {
34  string url; ///< Destination host
35  boolean allowOffTimeRangeCerts; ///< allow expired and not yet valid TLS certificates
36  string caCertChain; ///< TLS CA certificate chain
37  boolean useAuth; ///< \c true to use HTTP basic authentication
38  string username; ///< Authentication user name
39  string password; ///< Password; write-only, empty to leave unchanged
40  EntryType type; ///< Type of data
41  vector<string> items; ///< Included items (e.g. list of sensors) depending on type
42  };
43 
44  /**
45  * Data Push Entry Status
46  */
47  structure EntryStatus {
48  boolean busy; ///< \c true if the entry is currently being pushed
49  boolean rescheduled; ///< \c true if the entry is set to be pushed again
50  ///< immediately after completion
51  time lastAttemptTime; ///< UNIX timestamp (UTC) of the last push attempt (0 = never)
52  time lastSuccessTime; ///< UNIX timestamp (UTC) of last successful push (0 = never)
53  };
54 
55  /**
56  * Event: A new push destination has been added
57  */
58  valueobject EntryAddedEvent extends UserEvent {
59  int entryId; ///< New entry id
60  EntrySettings settings; ///< New entry settings
61  };
62 
63  /**
64  * Event: A configured push destination has been modified
65  */
66  valueobject EntryModifiedEvent extends UserEvent {
67  int entryId; ///< Modified entry id
68  EntrySettings oldSettings; ///< Settings before change
69  EntrySettings newSettings; ///< Settings after change
70  };
71 
72  /**
73  * Event: A configured push destination has been deleted
74  */
75  valueobject EntryDeletedEvent extends UserEvent {
76  int entryId; ///< Deleted entry id
77  };
78 
79  /**
80  * Event: The status of a configured push destination has changed
81  */
82  valueobject EntryStatusChangedEvent extends idl.Event {
83  int entryId; ///< Entry id
84  EntryStatus newStatus; ///< New status
85  };
86 
87  /**
88  * Add a new entry.
89  *
90  * @param entryId Result: New entry id, automatically assigned
91  * @param entrySettings New Model Push Entry settings
92  *
93  * @return 0 if OK
94  * @return 2 if the settings are invalid
95  * @return 3 if the maximum number of entries is reached
96  */
97  int addEntry(out int entryId, in EntrySettings entrySettings);
98 
99  /**
100  * Modify an existing entry.
101  *
102  * @param entryId Entry id
103  * @param entrySettings New Model Push Entry settings
104  *
105  * @return 0 if OK
106  * @return 1 if the entry does not exist
107  * @return 2 if the settings are invalid
108  */
109  int modifyEntry(in int entryId, in EntrySettings entrySettings);
110 
111  /**
112  * Delete an entry.
113  *
114  * @param entryid Entry id
115  *
116  * @return 0 if OK
117  * @return 1 if the entry does not exist
118  */
119  int deleteEntry(in int entryId);
120 
121  /**
122  * Retrieve an entry.
123  *
124  * @param entrySettings Result: Model Push Entry settings
125  * @param entryId Entry id
126  *
127  * @return 0 if OK
128  * @return 1 if the entry does not exist
129  */
130  int getEntry(out EntrySettings entrySettings, in int entryId);
131 
132  /**
133  * Retrieve a list of entries.
134  *
135  * @return List of Entry Settings
136  */
137  map<int, EntrySettings> listEntries();
138 
139  /**
140  * Push data for one specified entry
141  *
142  * @param entryId Entry id
143  *
144  * @return 0 if OK
145  * @return 1 if entry does not exist
146  *
147  */
148  int pushData(in int entryId);
149 
150  /**
151  * Cancels an active data push
152  *
153  * If a data push is currently in process for the specified entry,
154  * that push is canceled. If no push is in process, this method
155  * is a no-op.
156  *
157  * @param entryId Entry id
158  */
159  void cancelDataPush(in int entryId);
160 
161  /**
162  * Retrieve an entry's status.
163  *
164  * @param entryStatus Result: Entry status
165  * @param entryId Entry id
166  *
167  * @return 0 if OK
168  * @return 1 if the entry does not exist
169  */
170  int getEntryStatus(out EntryStatus entryStatus, in int entryId);
171 
172  };
173 
174 }
Data push service configuration interface.
Definition: DataPushService.idl:12
map< int, EntrySettings > listEntries()
Retrieve a list of entries.
EntryType
Data Push Entry Types.
Definition: DataPushService.idl:17
@ SENSORLIST
Sensor values for a set of sensors.
Definition: DataPushService.idl:18
@ AMSLOG
Asset Management log.
Definition: DataPushService.idl:21
@ SENSORLOG
Sensor log.
Definition: DataPushService.idl:19
@ AMSLIST
Asset Management information for a set of AMS strips.
Definition: DataPushService.idl:20
void cancelDataPush(in int entryId)
Cancels an active data push.
int pushData(in int entryId)
Push data for one specified entry.
int addEntry(out int entryId, in EntrySettings entrySettings)
Add a new entry.
int deleteEntry(in int entryId)
Delete an entry.
int getEntryStatus(out EntryStatus entryStatus, in int entryId)
Retrieve an entry's status.
int getEntry(out EntrySettings entrySettings, in int entryId)
Retrieve an entry.
int modifyEntry(in int entryId, in EntrySettings entrySettings)
Modify an existing entry.
Basic IDL definitions.
Definition: Event.idl:10
Event: A new push destination has been added.
Definition: DataPushService.idl:58
int entryId
New entry id.
Definition: DataPushService.idl:59
EntrySettings settings
New entry settings.
Definition: DataPushService.idl:60
Event: A configured push destination has been deleted.
Definition: DataPushService.idl:75
int entryId
Deleted entry id.
Definition: DataPushService.idl:76
Event: A configured push destination has been modified.
Definition: DataPushService.idl:66
EntrySettings oldSettings
Settings before change.
Definition: DataPushService.idl:68
EntrySettings newSettings
Settings after change.
Definition: DataPushService.idl:69
int entryId
Modified entry id.
Definition: DataPushService.idl:67
Data Push Entry Settings.
Definition: DataPushService.idl:33
EntryType type
Type of data.
Definition: DataPushService.idl:40
boolean useAuth
true to use HTTP basic authentication
Definition: DataPushService.idl:37
string url
Destination host.
Definition: DataPushService.idl:34
vector< string > items
Included items (e.g. list of sensors) depending on type.
Definition: DataPushService.idl:41
string caCertChain
TLS CA certificate chain.
Definition: DataPushService.idl:36
string username
Authentication user name.
Definition: DataPushService.idl:38
boolean allowOffTimeRangeCerts
allow expired and not yet valid TLS certificates
Definition: DataPushService.idl:35
string password
Password; write-only, empty to leave unchanged.
Definition: DataPushService.idl:39
Event: The status of a configured push destination has changed.
Definition: DataPushService.idl:82
EntryStatus newStatus
New status.
Definition: DataPushService.idl:84
int entryId
Entry id.
Definition: DataPushService.idl:83
Data Push Entry Status.
Definition: DataPushService.idl:47
time lastAttemptTime
UNIX timestamp (UTC) of the last push attempt (0 = never)
Definition: DataPushService.idl:51
boolean rescheduled
true if the entry is set to be pushed again immediately after completion
Definition: DataPushService.idl:49
boolean busy
true if the entry is currently being pushed
Definition: DataPushService.idl:48
time lastSuccessTime
UNIX timestamp (UTC) of last successful push (0 = never)
Definition: DataPushService.idl:52
This UserEvent may be used as base valueobject for all concrete events that are triggered because of ...
Definition: UserEvent.idl:19
Common base for all events.
Definition: Event.idl:13