amps-python-client 5.3.4.1__zip

amps-python-client-5.3.4.1/docs/command-reference/html/_sources/chapters/logon.rst.txt

@@ -0,0 +1,231 @@
+.. _#command-guide-logon:
+
+Logging on to AMPS
+==================================
+
+To help identify clients and users, it is recommended that clients send
+a ``logon`` command to the AMPS engine and specify a client name. By
+default, AMPS requires a ``logon`` command as the first command
+when a client connects. 
+
+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.
+
+.. note::
+
+  The ``websocket`` protocol uses a different
+  mechanism that contains the same information
+  rather than sending a ``logon`` command.
+
+Header Fields
+-------------
+
+The following table
+contains the header fields available to a ``logon`` command.
+
+.. _#command-logon-headers:
+
+.. list-table:: 
+     :header-rows: 1
+
+     * - **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.
+
+     * - ``Version``
+         
+
+       - The client library version (typical includes
+         the language and build number) of the client
+         making the connection. This version number
+         is logged for the connection, but does not
+         otherwise affect the connection.
+
+
+*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.
+
+The following table
+contains the acknowledgment messages that can be returned by a ``logon`` command.
+
+.. _#command-logon-acks:
+
+.. list-table:: 
+     :header-rows: 1
+
+     * - **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.
+
+
+*Acknowledgment messages supported by logon*
+
+
+Options Field
+^^^^^^^^^^^^^^
+
+The following table
+contains a list of the ``Options`` available and their definitions when used in the AMPS 
+``logon`` command.
+
+
+.. _#command-logon-options:
+
+
+.. list-table:: 
+     :header-rows: 1
+
+     * - **Option**
+
+       - **Description**
+
+     * - ``none``
+
+       - This is the default ``Options`` type.
+
+     * - ``ack_conflation``
+         
+
+       - When provided, the interval at which AMPS
+         conflates ``persisted`` acknowledgement messages
+         for publishes sent on this connection.
+         
+         AMPS conflates ``persisted`` acknowledgement
+         messages when a transaction log is configured
+         for the instance.
+         
+         Defaults to ``1s`` if no option is provided.
+
+     * - ``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.
+
+
+*Options supported by logon*
+
+