Translated Document

This document has been translated from the original Japanese by members of the Ukagaka Dream Team community.
To see the original document, click here.
To submit corrections/updates, see our repository to open an issue or find where to contact us.

SHIORI/3.0

Reference: SHIORI/3.0 (External site) SHIORI/2.x (External site)

Detection of implementation response status

The implementation support status of extension headers is notified at the beginning of SHIORI execution using ID: capability.

request

Sample

GET SHIORI/3.0
Charset: UTF-8
Sender: SSP
SenderType: internal,raise
SecurityLevel: local
Status: choosing,balloon(0=0)
ID: OnFirstBoot
BaseID: OnBoot
Reference0: 1

※The line feed code is CR+LF
※Terminate with a blank line ((CR+LF)x2 at the end of the last line).

Method

GET: A method that assumes that something will be returned in the Value header of the response.
NOTIFY: A method that is not expected to return any value. The Value header of the response is ignored.
It is mainly used when "unable to speak" due to some mode restriction, or for status notification events immediately after startup.
Note that the same ID (event name) may use both GET and NOTIFY.

Charset

Character code. Preferably before the first line, or at least before any line whose character code is not in the ASCII range.

Sender

Event source.

SenderType [Extended in SSP 2.5.05]

Attributes of the event source. The following attributes are used. If there is more than one, they are connected by commas.
For ID: OnTranslate, the attributes of the translate-source event are inherited.

internal: Events from inside the application.
external: Events from outside the application.
sakuraapi: An event caused by Sakura API.
embed: An event caused by the \![embed] tag.
raise: An event caused by the \![raise] tag.
property: An event caused as a result of a property system reference instruction.
plugin: An event caused by a plugin.
sstp: An event caused by SSTP.
communicate: An event caused by a communicate specification.

SecurityLevel

Security level when executing the script. One of the following.
For ID: OnTranslate, the attributes of the translate-source event are inherited.

Notified on the first line if at all possible. It should appear at least before the ID header.

local: Notifications from within the running terminal.
external: Notifications from outside the running terminal.

In the case of external, it is a notification from outside the running system, so it should be handled with caution for security reasons.
The concept is different from internal/external of SenderType. Even if the event is generated from outside the application, it will be judged as local if it can be regarded as safe, so the SecurityLevel may be local even if the SenderType is external.

SecurityOrigin [SSP extension]

A URL-like string indicating the source server. The format is as follows. The concept is the same as that of Origin in HTTP headers.
SecurityOrigin: null
SecurityOrigin: <scheme>://<hostname>
SecurityOrigin: <scheme>://<hostname>:<port>
scheme is usually http, https, or sstp. hostname is the name or IP of the source server. port is the port on which replies can be accepted.
It will be null if there is no information, such as when a header is not specified in SSTP, etc.
See also SecurityOrigin in the SSTP specification.

Status [SSP extension]

Ghost running state. As follows. If there is more than one, they are connected by commas.

talking: In the middle of talking.
choosing: Displaying menu choices.
minimizing: When minimized.
induction: During \![enter,inductionmode].
passive: During \![enter,passivemode].
timecritical: During time critical section (\t).
nouserbreak: During \![enter,nouserbreak].
online: Network communication in progress.
opening(type): An input box, etc., is open.
If multiple types are open, they are listed with / as the delimiter.
"dialog" is for file selection, color picker, etc.
Example: opening(communicate/input/teach/dialog)
balloon(ID group): Balloon is displayed.
Listed in the format character ID=balloon ID.
If more than one is open, they are listed with / as the delimiter.
Example: balloon(0=2/1=0), where \0 indicates a large balloon is being displayed and \1 indicates a normal balloon is being displayed.

ID

Event name or resource identifier

BaseID [SSP Extension]

Compatible base event names.
Example: Since OnFirstBoot is compatible with OnBoot, and OnFirstBoot is a variant of OnBoot, OnFirstBoot's BaseID will contain OnBoot.

Reference*

Additional information accompanying the event. A number is included after Reference. The number of lines is unlimited (as long as memory allows).

X-SSTP-PassThru-(Arbitrary string) [Extended in SSP 2.5.05]

If and only if an event notification is received from SSTP, the SSTP request header beginning with "X-SSTP-PassThru-" will be notified as is.
Not added when it is not SSTP.

response

Sample

SHIORI/3.0 200 OK
Charset: UTF-8
Sender: AYA
Value: \1\s[10]\0\s[0]\e

※The line feed code is CR+LF
※Terminate with a blank line ((CR+LF)x2 at the end of the last line).

Status code

As with HTTP, the number 200 indicates success, while the others indicate some kind of failure (error).
Currently, the following are primarily used.

200: 200 OK
Success, return value (Value) exists.
204: 204 No Content
Success, no return value.
311: 311 Not Enough
Indicates that additional information is required in ID: OnTeach (SHIORI/2 series TEACH method).
Reopen the input box, ask the user, and add a Reference containing the input string after input is complete.
312: 312 Advice
Indicates that the most recently input string in ID: OnTeach (SHIORI/2 series TEACH method) is uninterpretable and should be discarded.
Discard the last Reference, reopen the input box, ask the user, and add a Reference containing the input string after input is complete.
400: 400 Bad Request
Request string was uninterpretable.
500: 500 Internal Server Error
Some error occured within SHIORI and a response could not be returned.

Charset

Character code. Preferably before the first line, or at least before any line whose character code is not in the ASCII range.

Sender

Sender. Usually the name of the SHIORI.

Value

Script to be spoken.

ValueNotify [SSP Extension 2.5.35]

[Experimental feature]
Extension for executing SakuraScript even when the request method is NOTIFY.
If SakuraScript is returned with this header, it is executed immediately.
The number of tags that can be executed is extremely limied; all other tags and strings are ignored.
It is ignored when the method is not NOTIFY or if the Value header is already present.
Currently, the following tags can be executed:

\![sound]
\![set,trayicon]
\![set,trayballoon]
\![raise] (It works the same as NOTIFY)
\![raiseother] (It works the same as NOTIFY)
\![raiseplugin] (It works the same as NOTIFY)
\![timerraiseother] (The event will be treated as a NOTIFY event)
\![timerraiseplugin] (The event will be treated as a NOTIFY event)
\![notify]
\![notifyother]
\![notifyplugin]

SecurityLevel [SSP Extension]

One of the following.

local: Security level equivalent to scripts from inside the running terminal.
external: Security level equivalent to scripts from outside the running terminal.

SecurityLevel of the script to be spoken. If it is external, some scripts will not be able to be executed due to security features.

Marker [SSP Extension]

String to be displayed on the balloon marker (additional information on the underside of the ballon).

ErrorLevel [SSP Extension]

The level of error that occurred inside the SHIORI. One of the following. To express multiple errors, separate them with a byte value of 1.

info: Information. Not an error.
notice: Notice. A description that is not an error but should be corrected, etc.
warning: Warning. A warning is a description error that should be addressed, although the process has not been stopped.
error: Normal error. Something has stopped due to a description error, etc., and cannot be resumed.
critical: Fatal error, worse than a normal error and needs to be addressed immediately.

If this header is present, the user is notified that an error has occurred.
The level of notification is user-configurable. Usually, it is error or higher.
In the case of SSP, it is recorded in the error log and an error icon appears in the notification area.

ErrorDescription [SSP Extension]

Detailed information on errors that occurred inside the SHIORI. Valid only if ErrorLevel is present.
To express multiple errors, separate them with a byte value of 1
The number of elements in ErrorLevel and ErrorDescription must be the same.

BalloonOffset [SSP Extension]

Offset value (X,Y) of the balloon.

Reference0

Name of the \0 side of the ghost if you want to send a communication.

Reference1+

Additional information for communication.
Reference1 in response = Reference0 in SSTP communicate = Reference2 in the receiver's OnCommunicate.
Note that the above is out of alignment due to compatibility issues.

Age [SSP Extension]

Number of generations of communication. 0 for the first time, +1 for each successive exchange.
Although it is an SSP extension, it is actually SHIORI/2.x compatible processing.

MarkerSend [SSP Extension]

A balloon marker string that you want to display "to the other side" while communicating.
Sent as a Marker header of SSTP.

X-SSTP-PassThru-(Arbitrary string) [Extended in SSP 2.5.03]

If and only if an event notification is received from SSTP, this header is added to the SSTP response as it is.
Not added when it is not SSTP.
Multiple headers can be specified, but if you want to return more than one, change the header name.
(Old header name: X-SSTP-Return- , will be deprecated.)