Skip to content

Commit b5914b1

Browse files
nuustiknuustik
committed
Improve documentation about security
1 parent 56b76f9 commit b5914b1

3 files changed

Lines changed: 114 additions & 60 deletions

File tree

‎README.rst‎

Lines changed: 104 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,67 @@ request.systemUseNotification()
7676

7777
System use notification message to ask for confirmation to continue.
7878

79+
request.userAuthResult()
80+
^^^^^^^^^^^^^^^^^^^^^^^^
81+
82+
- Returns
83+
84+
Authentication response if security is enabled.
85+
86+
87+
studio.api.UserAuthResult(code, text, additionalCredentials)
88+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
89+
90+
- Arguments
91+
92+
code - response code.
93+
94+
text - response info/error.
95+
96+
additionalCredentials - Returns additional credentials if required by received response code.
97+
98+
- Returns
99+
100+
The created UserAuthResult object.
101+
102+
Instance Methods / UserAuthResult
103+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104+
105+
result.code()
106+
^^^^^^^^^^^^^
107+
108+
- Returns
109+
110+
Authentication response code.
111+
112+
+---------------------------------+------------------------------------------------------------------------------------------------------------------+
113+
| Type | Description |
114+
+=================================+==================================================================================================================+
115+
| studio.protocol.AuthResultCode | Optional: One of the following: |
116+
| | eCredentialsRequired |
117+
| | eGranted |
118+
| | eGrantedPasswordWillExpireSoon // expiry timestamp is provided by text() |
119+
| | eNewPasswordRequired // AuthRequest with additional response with new username + password hash is required |
120+
| | eInvalidChallengeResponse // challenge response sent was invalid |
121+
| | eAdditionalResponseRequired // additional challenge responses based on additional credential types are required. |
122+
| | eTemporarilyBlocked // authentication is temporarily blocked because of too many failed attempts |
123+
| | eNodeIseReauthenticationRequiredInternal // server requires re-authentication (e.g. because of being idle) |
124+
| | // implementation should prompt the user for re-authentication |
125+
+---------------------------------+------------------------------------------------------------------------------------------------------------------+
126+
127+
result.text()
128+
^^^^^^^^^^^^^
129+
130+
- Returns
131+
132+
Authentication error or info in text representation.
133+
134+
result.additionalCredentials()
135+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
136+
137+
- Returns
138+
139+
Returns additional credentials if required.
79140

80141
studio.api.Client(uri, notificationListener)
81142
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -124,11 +185,11 @@ studio.api.Client(uri, notificationListener)
124185
125186
credentialsRequested(request) {
126187
return new Promise(function(resolve, reject) {
127-
if (request.userAuthResult().code() == studio.api.CREDENTIALS_REQUIRED) {
188+
if (request.userAuthResult().code() == studio.protocol.AuthResultCode.eCredentialsRequired) {
128189
// Do something to gather username and password variables (either sync or async way) and then call:
129190
resolve({Username: "cdpuser", Password: "cdpuser"});
130191
}
131-
if (request.userAuthResult().code() == studio.api.REAUTHENTICATIONREQUIRED) {
192+
if (request.userAuthResult().code() == studio.protocol.AuthResultCode.eReauthenticationRequired) {
132193
// Pop user a message that idle lockout was happened and server requires new authentication to continue:
133194
resolve({Username: "cdpuser", Password: "cdpuser"});
134195
}
@@ -456,47 +517,47 @@ node.subscribeToEvents(eventConsumer, timestampFrom)
456517

457518
Subscribe to events on this node. On each event eventConsumer function is called with Event argument described here:
458519

459-
+-------------------+----------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
460-
| Property | Type | Description |
461-
+===================+==================================+=================================================================================================================================+
462-
| Event.id | number | Optional: System unique eventId (CDP eventId + handle) |
463-
+-------------------+----------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
464-
| Event.sender | string | Optional: Event sender full name |
465-
+-------------------+----------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
466-
| Event.flags | studio.protocol.EventCodeFlags | Optional: Event code flags. Any of: |
467-
| | | eAlarmSet = 1; // The alarm's Set flag/state was set. The alarm changed state to "Unack-Set" |
468-
| | | eAlarmClr = 2; // The alarm's Set flag was cleared. The Unack state is unchanged. |
469-
| | | eAlarmAck = 4; // The alarm changed state from "Unacknowledged" to "Acknowledged". The Set state is unchanged. |
470-
| | | eReprise = 64; // A repetition/update of an event that has been reported before. Courtesy of late subscribers. |
471-
| | | eSourceObjectUnavailable = 256; // The provider of the event has become unavailable. (disconnected or similar) |
472-
| | | eNodeBoot = 1073741824; // The provider reports that the CDPEventNode just have booted. |
473-
+-------------------+----------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
474-
| Event.status | studio.protocol.EventStatusFlags | Optional: Value primitive type the node holds if node may hold a value. Any of: |
475-
| | | eStatusOK = 0x0, // No alarm set |
476-
| | | eNotifySet = 0x1, // NOTIFY alarm set |
477-
| | | eWarningSet = 0x10, // WARNING alarm set |
478-
| | | eLowLevelSet = 0x20, // LOW LEVEL alarm set |
479-
| | | eHighLevelSet = 0x40, // HIGH LEVEL alarm set |
480-
| | | eErrorSet = 0x100, // ERROR alarm set |
481-
| | | eLowLowLevelSet = 0x200, // LOW-LOW LEVEL alarm set |
482-
| | | eHighHighLevelSet = 0x400, // HIGH-HIGH LEVEL alarm set |
483-
| | | eEmergencySet = 0x800, // EMERGENCY LEVEL alarm present |
484-
| | | eValueForced = 0x1000, // Signal value was forced (overridden) |
485-
| | | eRepeatBlocked = 0x2000, // Alarm is blocked due to too many repeats |
486-
| | | eProcessBlocked = 0x4000, // Alarm is blocked by the software |
487-
| | | eOperatorBlocked = 0x8000, // Alarm is blocked by the user |
488-
| | | eNotifyUnacked = 0x10000, // NOTIFY alarm unacknowledged |
489-
| | | eWarningUnacked = 0x100000, // WARNING alarm unacknowledged |
490-
| | | eErrorUnacked = 0x1000000, // ERROR alarm unacknowledged |
491-
| | | eEmergencyUnacked = 0x8000000, // EMERGENCY alarm unacknowledged |
492-
| | | eDisabled = 0x20000000, // Alarm is disabled |
493-
| | | eSignalFault = 0x40000000, // Signal has fault condition |
494-
| | | eComponentSuspended = 0x80000000 // Component is suspended |
495-
+-------------------+----------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
496-
| Event.timestamp | string | Optional: time stamp, when this event was sent (in UTC nanotime) |
497-
+-------------------+----------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
498-
| Event.data | string | Optional: name + value pairs |
499-
+-------------------+----------------------------------+---------------------------------------------------------------------------------------------------------------------------------+
520+
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------+
521+
| Property | Type | Description |
522+
+===================+=============================+=================================================================================================================================+
523+
| Event.id | number | Optional: System unique eventId (CDP eventId + handle) |
524+
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------+
525+
| Event.sender | string | Optional: Event sender full name |
526+
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------+
527+
| Event.code | studio.protocol.EventCode | Optional: Event code flags. Any of: |
528+
| | | eAlarmSet = 1; // The alarm's Set flag/state was set. The alarm changed state to "Unack-Set" |
529+
| | | eAlarmClr = 2; // The alarm's Set flag was cleared. The Unack state is unchanged. |
530+
| | | eAlarmAck = 4; // The alarm changed state from "Unacknowledged" to "Acknowledged". The Set state is unchanged. |
531+
| | | eReprise = 64; // A repetition/update of an event that has been reported before. Courtesy of late subscribers. |
532+
| | | eSourceObjectUnavailable = 256; // The provider of the event has become unavailable. (disconnected or similar) |
533+
| | | eNodeBoot = 1073741824; // The provider reports that the CDPEventNode just have booted. |
534+
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------+
535+
| Event.status | studio.protocol.EventStatus | Optional: Value primitive type the node holds if node may hold a value. Any of: |
536+
| | | eStatusOK = 0x0, // No alarm set |
537+
| | | eNotifySet = 0x1, // NOTIFY alarm set |
538+
| | | eWarningSet = 0x10, // WARNING alarm set |
539+
| | | eLowLevelSet = 0x20, // LOW LEVEL alarm set |
540+
| | | eHighLevelSet = 0x40, // HIGH LEVEL alarm set |
541+
| | | eErrorSet = 0x100, // ERROR alarm set |
542+
| | | eLowLowLevelSet = 0x200, // LOW-LOW LEVEL alarm set |
543+
| | | eHighHighLevelSet = 0x400, // HIGH-HIGH LEVEL alarm set |
544+
| | | eEmergencySet = 0x800, // EMERGENCY LEVEL alarm present |
545+
| | | eValueForced = 0x1000, // Signal value was forced (overridden) |
546+
| | | eRepeatBlocked = 0x2000, // Alarm is blocked due to too many repeats |
547+
| | | eProcessBlocked = 0x4000, // Alarm is blocked by the software |
548+
| | | eOperatorBlocked = 0x8000, // Alarm is blocked by the user |
549+
| | | eNotifyUnacked = 0x10000, // NOTIFY alarm unacknowledged |
550+
| | | eWarningUnacked = 0x100000, // WARNING alarm unacknowledged |
551+
| | | eErrorUnacked = 0x1000000, // ERROR alarm unacknowledged |
552+
| | | eEmergencyUnacked = 0x8000000, // EMERGENCY alarm unacknowledged |
553+
| | | eDisabled = 0x20000000, // Alarm is disabled |
554+
| | | eSignalFault = 0x40000000, // Signal has fault condition |
555+
| | | eComponentSuspended = 0x80000000 // Component is suspended |
556+
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------+
557+
| Event.timestamp | string | Optional: time stamp, when this event was sent (in UTC nanotime) |
558+
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------+
559+
| Event.data | string | Optional: name + value pairs |
560+
+-------------------+-----------------------------+---------------------------------------------------------------------------------------------------------------------------------+
500561

501562
- Example
502563

0 commit comments

Comments
 (0)