2. logon¶
Description¶
To help identify clients and users, it is recommended that clients send
a logon
command to the AMPS engine and specify a client name.
AMPS only allows a single logon
command for each connection. The
logon
command must be the first command sent over a new connection.
Otherwise, AMPS performs an implicit logon
, causing any other
logon
commands for the connection to be rejected.
In AMPS configurations where authentication is enabled, all connecting
clients must issue a logon
message with the username
and
password
credentials specified in the command. Attempts to logon to
an AMPS instance that do not contain the information required will be
rejected and prohibited from issuing further commands until a successful
logon
has been placed.
If an AMPS client is connected to an instance that has a transaction log
enabled, the ClientName
specified must be unique for the instance.
Only one client with the same name is allowed to connect to the instance at a
given time. If an application logs on with the same ClientName
and
authenticated user name as an existing connection, AMPS assumes that the new
logon is a reconnection from the existing connection and disconnects the
existing connection. If an application logs on with the same ClientName
as
an existing connection but a different authenticated user name, the new logon
will fail.
It is recommended that all logon
commands request that a
processed
acknowledgment message be requested in the AckType
header of the logon
message. This will allow AMPS to communicate the
result of the logon
command to the client, allowing the client to
determine how to best proceed.
Header Fields¶
Table 2.1
contains the header fields available to a logon
command.
Field | Description |
---|---|
Command
|
The command to be executed. Value: logon . |
ClientName
|
A string identifier used to give a client a unique id. AMPS does not limit the character set used in this name. However, the specific protocol may have character set limitations. 60East recommends that the client name is meaningful, short, human readable, and avoids using control characters, newline characters, or square brackets. |
AckType |
Acknowledgment type for the given command. Value
is a comma separated list of one or more of the
following: none , received or
processed . |
MessageType |
The message type for the connection. Required if the Transport accepts any message type. |
UserId |
The username passed into the AMPS authentication and entitlement module. |
Password |
The password passed into the AMPS authentication and entitlement module. |
CorrelationId |
A user-provided string that will be included in
the log message recording this logon, and in the
information provided for the connection in the
administration interface. AMPS does not
interpret this string or use the string for any
other purpose. If this header is not present,
AMPS does not store a value for the
CorrelationId for this connection. The
contents of this header must consist of
characters that are legal in Base64 encoding. |
Table 2.1: Header fields supported by logon
Returns¶
A logon
message specifying an AckType
of received
or
processed
will receive an ack
message to acknowledge the message
receipt. If a client requests an acknowledgment message, the header will
also contain the ClientName
which was part of the original logon
message.
When requested, the logon
command will result in a processed
acknowledgment message. This returned acknowledgment is used in
determining if a client was successfully authenticated against a server
which has an authentication module enabled.
Table 2.2
contains the acknowledgment messages that can be returned by a logon
command.
Acknowledgment | Description |
---|---|
none |
No ack message is returned. This is the
default behavior. |
completed |
Not supported at this time. |
persisted |
Not supported at this time. |
processed |
AMPS has processed the logon message. |
received |
The logon command has been received. |
stats |
Not supported at this time. |
Table 2.2: Acknowledgment messages supported by logon
Options Field¶
Table 2.3
contains a list of the Options
available and their definitions when used in the AMPS
logon
command.
Option | Description |
---|---|
none |
This is the default Options type. |
ack_conflation |
When provided, the interval at which AMPS
conflates AMPS conflates Defaults to |
pretty |
When provided and set to true , AMPS returns
a formatted representation of the contents of
the built-in binary message types rather than
the original data. |
Table 2.3: Options supported by logon