Class SAMPIntegratedClient

SAMPIntegratedClient constructor.

Parameters:

• metadata (dict) - (optional) a dictionary containing the client application metadata in the standard SAMP format
• addr (string) - (optional) 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__

Testing method to verify the client connection with a running Hub.

Returns: boolean

return True if the client is connected to a Hub, False otherwise

Connect with the current or specified SAMP Hub, start and register the client. If a SAMP Hub is not running or refuses the connection, then a SAMPHubError is raised.

Parameters:

• hub_params (dictionary) - Optional dictionary containig the lock-file content of the Hub with which to connect. This dictionary has the form {<token-name>: <token-string>, ...}.
• user (string) - In case of Basic Authenticated connections, user specifies the user name.
• password (string) - In case of Basic Authenticated connections, password specifies the user password.
• key_file (string) - Set the file containing the private key for SSL connections. If the certificate file (certfile) contains the private key, then keyfile 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 server 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 server 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_SSLv3. This version provides the most compatibility with other versions server side. Other SSL protocol versions are: ssl.PROTOCOL_SSLv2, ssl.PROTOCOL_SSLv23 and ssl.PROTOCOL_TLSv1.

Easy notify. It is a proxy to notify method that allows to send the notification message in a simplified way. Example:

>>> import sampy
>>> cli = sampy.SAMPIntegratedClient()
>>> ...
>>> cli.enotify("samp.msg.progress", msgid = "xyz", txt = "initialization", \
>>>             percent = "10", extra_kws = {"my.extra.info": "just an example"})

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:

• recipient_id (string) - the recipient ID
• mtype (string) - the MType to be notified
• params (dictionary or set of keywords) - variable keyword set which contains the list of parameters for the specified MType

Easy notify. It is a proxy to notifyAll method that allows to send the notification message in a simplified way. Example:

>>> import sampy
>>> cli = sampy.SAMPIntegratedClient()
>>> ...
>>> cli.enotifyAll("samp.msg.progress", txt = "initialization", \
>>>                percent = "10", extra_kws = {"my.extra.info": "just an example"})

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:

• mtype (string) - the MType to be notified
• params (dictionary or set of keywords) - variable keyword set which contains the list of parameters for the specified MType

Easy call. It is a proxy to call method that allows to send a call message in a simplified way. Example:

>>> import sampy
>>> cli = sampy.SAMPIntegratedClient()
>>> ...
>>> msgid = cli.ecall("abc", "xyz", "samp.msg.progress", txt = "initialization", \
>>>                   percent = "10", extra_kws = {"my.extra.info": "just an example"})

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:

• recipient_id (string) - the recipient ID
• msg_tag (string) - the message tag to use
• mtype (string) - the MType to be sent
• params (dictionary or set of keywords) - variable keyword set which contains the list of parameters for the specified MType

Easy callAll. It is a proxy to callAll method that allows to send the call message in a simplified way. Example:

>>> import sampy
>>> cli = sampy.SAMPIntegratedClient()
>>> ...
>>> msgid = cli.ecallAll("xyz", "samp.msg.progress", txt = "initialization", \
>>>                      percent = "10", extra_kws = {"my.extra.info": "just an example"})

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:

• msg_tag (string) - the message tag to use
• mtype (string) - the MType to be sent
• params (dictionary or set of keywords) - variable keyword set which contains the list of parameters for the specified MType

Proxy to callAndWait SAMP Hub method. If timeout expires a SAMPProxyError instance is raised.

Easy callAndWait. It is a proxy to callAll method that allows to send the call message in a simplified way. Example:

>>> import sampy
>>> cli = sampy.SAMPIntegratedClient()
>>> ...
>>> cli.ecallAndWait("xyz", "samp.msg.progress", "5", txt = "initialization", \
>>>                  percent = "10", extra_kws = {"my.extra.info": "just an example"})

Note that reserved extra_kws keyword is a dictionary with the special meaning of being used to add extra keywords, in addition to the standard samp.mtype and samp.params, to the message sent.

Parameters:

• recipient_id (string) - the recipient ID
• mtype (string) - the MType to be sent
• timeout (string) - the call timeout in seconds
• params (dictionary or set of keywords) - variable keyword set which contains the list of parameters for the specified MType

Easy reply. It is a proxy to callAll method that allows to send a reply message in a simplified way. Example:

>>> import sampy
>>> cli = sampy.SAMPIntegratedClient()
>>> ...
>>> cli.ereply("abd", sampy.SAMP_STATUS_ERROR, result = {}, error = {"samp.errortxt": "Test error message"})

Parameters:

• msg_id (string) - the message ID to which reply
• status (string) - the content of the samp.status response keyword
• result (dictionary) - the content of the samp.result response keyword
• error (dictionary) - the content of the samp.error response keyword

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.

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