Class SAMPClient

SAMPClient constructor.

Parameters:

• hub (SAMPHubProxy) - an instance of SAMPHubProxy to be used for messaging with the SAMP Hub.
• metadata (dict) - (optional) a dictionary containing the client application metadata in the standard SAMP format
• addr (string) - Listening address (or IP)
• port (int) - (optional) the listening XML-RPC server socket port
• https (boolean) - set the callable client running on a Secure Sockets Layer connection (HTTPS). By default SSL is desabled.
• key_file (string) - Set the file containing the private key for SSL connections. If the certificate file (cert_file) contains the private key, then key_file can be omitted.
• cert_file (string) - Specify the file which contains a certificate to be used to identify the local side of the secure connection.
• cert_reqs (int) - The parameter cert_reqs specifies whether a certificate is required from the Hub side of the connection, and whether it will be validated if provided. It must be one of the three values ssl.CERT_NONE (certificates ignored), ssl.CERT_OPTIONAL (not required, but validated if provided), or ssl.CERT_REQUIRED (required and validated). If the value of this parameter is not ssl.CERT_NONE, then the ca_certs parameter must point to a file of CA certificates.
• ca_certs (string) - The ca_certs file contains a set of concatenated "Certification Authority" certificates, which are used to validate the certificate passed from the Hub end of the connection.
• ssl_version (int) - The ssl_version option specifies which version of the SSL protocol to use. Typically, the server chooses a particular protocol version, and the client must adapt to the server's choice. Most of the versions are not interoperable with the other versions. If not specified the default SSL version is ssl.PROTOCOL_SSLv23. This version provides the most compatibility with other versions Hub side. Other SSL protocol versions are: ssl.PROTOCOL_SSLv2, ssl.PROTOCOL_SSLv3 and ssl.PROTOCOL_TLSv1.
• callable (boolean) - specify whether the client is a callable client or not

Overrides: object.__init__

Return an information concerning the client running status.

Returns: boolean

True if the client is running, False otherwise

Standard callable client receiveNotification method. This method is automatically handled when bindReceiveNotification method is used to bind distinct operations to MTypes. In case of a customized callable client implementation that inherits from SAMPClient class this method should be overwritten. ATTENTION: when overwritten, this method must always return a string result (even empty).

Parameters:

• private_key (str) - the client private key.
• sender_id (str) - the sender public ID.
• message (dict) - the message received.

Returns: str

any confirmation string.

Standard callable client receiveCall method. This method is automatically handled when bindReceiveCall method is used to bind distinct operations to MTypes. In case of a customized callable client implementation that inherits from SAMPClient class this method should be overwritten. ATTENTION: when overwritten, this method must always return a string result (even empty).

Parameters:

• private_key (str) - the client private key.
• sender_id (str) - the sender public ID.
• msg_id (str) - the message ID received.
• message (dict) - the message received.

Returns: str

any confirmation string.

Standard callable client receiveResponse method. This method is automatically handled when bindReceiveResponse method is used to bind distinct operations to MTypes. In case of a customized callable client implementation that inherits from SAMPClient class this method should be overwritten. ATTENTION: when overwritten, this method must always return a string result (even empty).

Parameters:

• private_key (str) - the client private key.
• responder_id (str) - the responder public ID.
• msg_tag (str) - the response message tag.
• response (dict) - the response received.

Returns: str

any confirmation string.

Bind a specific MType to a function or class method, being intended for a call or a notification.

The function must be of the form: def my_function_or_method(<self,> private_key, sender_id, msg_id, mtype, params, extra)

where private_key is the client private-key, sender_id argument is the notification sender ID, msg_id is the Hub message-id (calls only, otherwise is None), mtype is the message MType, params is the message parameter set (content of "samp.params") and extra is a dictionary containing any extra message map entry. The client is automatically declared subscribed to the MType by default.

Parameters:

• mtype (str) - the MType to be catched.
• function (function or class method) - the application function to be used when mtype is received.
• declare (boolean) - specify whether the client must be automatically declared as subscribed to the MType (see also declareSubscriptions).
• metadata (dict) - an optional map containing additional metadata to declare associated with the MType subscribed to (see also declareSubscriptions).

Bind a specific MType notification to a function or class method. The function must be of the form:

def my_function_or_method(<self,> private_key, sender_id, mtype, params, extra)

where private_key is the client private-key, sender_id argument is the notification sender ID, mtype is the message MType, params is the notified message parameter set (content of "samp.params") and extra is a dictionary containing any extra message map entry. The client is automatically declared subscribed to the MType by default.

Parameters:

• mtype (str) - the MType to be catched.
• function (function or class method) - the application function to be used when mtype is received.
• declare (boolean) - specify whether the client must be automatically declared as subscribed to the MType (see alse declareSubscriptions).
• metadata (dict) - an optional map containing additional metadata to declare associated with the MType subscribed to (see also declareSubscriptions).

Bind a specific MType call to a function or class method. The function must be of the form:

def my_function_or_method(<self,> private_key, sender_id, msg_id, mtype, params, extra)

where private_key is the client private-key, sender_id argument is the notification sender ID, msg_id is the Hub message-id, mtype is the message MType, params is the message parameter set (content of "samp.params") and extra is a dictionary containing any extra message map entry. The client is automatically declared subscribed to the MType by default.

Parameters:

• mtype (str) - the MType to be catched.
• function (function or class method) - the application function to be used when mtype is received.
• declare (boolean) - specify whether the client must be automatically declared as subscribed to the MType (see also declareSubscriptions).
• metadata (dict) - an optional map containing additional metadata to declare associated with the MType subscribed to (see also declareSubscriptions).

Bind a specific msg-tag response to a function or class method. The function must be of the form:

def my_function_or_method(<self,> private_key, responder_id, msg_tag, response)

where private_key is the client private-key, responder_id argument is the message responder ID, msg_tag is the message-tag provided at call time and response is the response received.

Parameters:

• msg_tag (str) - the message-tag to be catched.
• function (function or class method) - the application function to be used when msg_tag is received.

Remove from the notifications binding table the specified MType and unsubscribe the client from it (if required).

Parameters:

• mtype (str) - the MType to be removed
• declare (boolean) - specify whether the client must be automatically declared as unsubscribed from the MType (see alse declareSubscriptions).

Remove from the calls binding table the specified MType and unsubscribe the client from it (if required).

Parameters:

• mtype (str) - the MType to be removed
• declare (boolean) - specify whether the client must be automatically declared as unsubscribed from the MType (see alse declareSubscriptions).

Remove from the responses binding table the specified message-tag.

Parameters:

• msg_tag (str) - the message-tag to be removed

Declares the MTypes the client wishes to subscribe to, implicitly defined with the MType binding methods bindReceiveNotification and bindReceiveCall. An optional subscriptions map can be added to the final map passed to the SAMPHubProxy.declareSubscriptions operation.

Parameters:

• subscriptions (dict) - an optional map containing the list of MTypes to subscribe to, with the same format of the subscriptions map passed to the SAMPHubProxy.declareSubscriptions operation.

Register the client to the SAMP Hub. If the registration fails a SAMPClientError is reaised.

Unregister the client from the SAMP Hub. If the unregistration fails a SAMPClientError is reaised.

Declare the client application metadata supported.

Parameters:

• metadata (dict) - (optional) dictionary containig the client application metadata as defined in the SAMP definition document. If omitted, then none metadata are declared.

Return the client private key used for the Standard Profile communications obtained at registration time (samp.private-key).

Returns: string

the client private key

Return public client ID obtained at registration time (samp.self-id).

Returns: string

the client public ID