Welcome to socket_protocol’s documentation!

socket_protocol (Socket Protocol)

Author:

Description:

This Module supports point to point communication for client-server issues.

Submodules:

Unittest:

See also the unittest documentation.

Module Documentation:

socket_protocol.AUTH_STATE_KEY_TRANSFERRED = 3

Authentification Status for ‘Key has been sent’

socket_protocol.AUTH_STATE_SEED_REQUESTED = 1

Authentification Status for ‘Seed was requested’

socket_protocol.AUTH_STATE_SEED_TRANSFERRED = 2

Authentification Status for ‘Seed has been sent’

socket_protocol.AUTH_STATE_TRUSTED_CONNECTION = 4

Authentification Status for a ‘Trusted Connection’

socket_protocol.AUTH_STATE_UNTRUSTED_CONNECTION = 0

Authentification Status for an ‘Untrusted Connection’

socket_protocol.AUTH_STATE__NAMES = {0: 'Untrusted Connection', 1: 'Seed was requested', 2: 'Seed has been sent', 3: 'Key has been sent', 4: 'Trusted Connection'}

Authentification Status names for previous defined authentification states

socket_protocol.DID_AUTH_KEY = 1

DID for authentification (key)

socket_protocol.DID_AUTH_SEED = 0

DID for authentification (seed)

socket_protocol.DID_CHANNEL_NAME = 0

DID for channel name

exception socket_protocol.RequestSidExistsError
exception socket_protocol.ResponseSidExistsError
socket_protocol.SID_AUTH_REQUEST = 0

SID for authentification request

socket_protocol.SID_AUTH_RESPONSE = 1

SID for authentification response

socket_protocol.SID_CHANNEL_NAME_REQUEST = 8

SID for channel name exchange request

socket_protocol.SID_CHANNEL_NAME_RESPONSE = 9

SID for channel name exchange response

socket_protocol.SID_EXECUTE_REQUEST = 30

SID for a execute request

socket_protocol.SID_EXECUTE_RESPONSE = 31

SID for a execute response

socket_protocol.SID_READ_REQUEST = 10

SID for a read data request

socket_protocol.SID_READ_RESPONSE = 11

SID for read data response

socket_protocol.SID_WRITE_REQUEST = 20

SID for a write data request

socket_protocol.SID_WRITE_RESPONSE = 21

SID for a write data response

socket_protocol.STATUS_AUTH_REQUIRED = 3

Status for ‘authentification is required’

socket_protocol.STATUS_BUFFERING_UNHANDLED_REQUEST = 1

Status for ‘unhandled request’

socket_protocol.STATUS_CALLBACK_ERROR = 2

Status for ‘callback errors’

socket_protocol.STATUS_CHECKSUM_ERROR = 5

Status for ‘checksum error’

socket_protocol.STATUS_OKAY = 0

Status for ‘okay’

socket_protocol.STATUS_OPERATION_NOT_PERMITTED = 6

Status for ‘operation not permitted’

socket_protocol.STATUS_SERVICE_OR_DATA_UNKNOWN = 4

Status for ‘service or data unknown’

class socket_protocol.data_storage(*args, **kwargs)

This is a storage object for socket_protocol messages.

Parameters:
  • status (int) – The message status.
  • service_id (int) – The Service-ID.
  • data_id (int) – The Data-ID.
  • data (any) – The transfered data.
get_data(default=None)

This Method returns the message data.

Parameters:default – The default value, if no data is available.
get_data_id(default=None)

This Method returns the message Data-ID.

Parameters:default – The default value, if no data is available.
get_service_id(default=None)

This Method returns the message Service-ID.

Parameters:default – The default value, if no data is available.
get_status(default=None)

This Method returns the message status.

Parameters:default – The default value, if no data is available.
class socket_protocol.pure_json_protocol(comm_instance, secret=None, auto_auth=False, channel_name=None)

This class supports to transfer a message and it’s data.

Parameters:
  • comm_instance (instance) – A communication instance.
  • secret (str) – An optinal secret (e.g. created by binascii.hexlify(os.urandom(24))).
  • auto_auth (bool) – An optional parameter to enable (True) automatic authentification, otherwise you need to do it manually, if needed.
  • channel_name (str) – An optional parameter to set a channel name for logging of the communication.

Hint

  • The Service-ID is designed to identify the type of the communication (e.g. READ_REQUEST, WRITE_REQUEST, READ_RESPONSE, WRITE_RESPONSE, …)
  • The Data-ID is designed to identify the requests / responses using the same Service_ID.

Note

The comm_instance needs to have at least the following interface:

  • A Method comm_instance.init_channel_name() to set the channel name.
  • A Constant comm_instance.IS_CLIENT to identify that the comm_instance is a client (True) or a server (False).
  • A Method comm_instance.is_connected() to identify if the instance is connected (True) or not (False).
  • A Method comm_instance.reconnect() to initiate a reconnect.
  • A Method comm_instance.register_callback() to register a data available callback.
  • A Method comm_instance.register_connect_callback() to register a connect callback.
  • A Method comm_instance.register_disconnect_callback() to register a disconnect callback.
  • A Method comm_instance.send() to send data via the comm_instance.

Note

The parameter auto_auth is only relevant, if a secret is given and the comm_instance is a client. The authentification is initiated directly after the connection is established.

Note

The channel_name-exchange will be initiated by the client directly after the the connection is established.

  • If a channel_name is given at both communication sides and they are different, the client name is taken over and the server will log a warning message.
add_data(service_id, data_id, name)

Method to add a name for a specific message.

Parameters:
  • service_id (int or list of ints) – The Service-ID of the message. See class definitions starting with SID_.
  • data_id (int) – The Data-ID of the message.
  • name (str) – The Name for the transfered message.
add_msg_to_auth_whitelist_(service_id, data_id)

Method to add a specific message to the list, where no authentification is required.

Parameters:
  • service_id (int) – The Service-ID of the message. See class definitions starting with SID_.
  • data_id (int) – The Data-ID of the message.
add_service(req_sid, resp_sid, req_name=None, resp_name=None)

Method to add a Service defined by Request- and Response Serivce-ID.

Parameters:
  • req_sid (int) – The Request Service-ID.
  • resp_sid (int) – The Response Service-ID.
add_status(status, name)

Method to add a name for a status.

Parameters:
  • status (int) – The Status. See class definitions starting with STATUS_.
  • name (str) – The Name for the Status.
authentificate(timeout=2)

This method authetificates the client at the server.

Parameters:timeout (float) – The timeout for the authentification (requesting seed, sending key and getting authentification_feedback).
Returns:True, if authentification was successfull; False, if not.
Return type:bool

Note

An authentification will only processed, if a secret had been given on initialisation.

Note

Client and Server needs to use the same secret.

check_authentification_state()

This Method return the Authitification State as boolean value.

Returns:True, if authentification state is okay, otherwise False
Return type:bool
connection_established()

This Method returns the Connection state including authentification as a boolean value.

Returns:True, if the connection is established (incl. authentification, if a secret has been given)
Return type:bool
is_connected()

This Methods returns Connection state of the Communication Instance comm_instance.is_connected().

Returns:True if the comm_instance is connected, otherwise False..
Return type:bool
receive(service_id, data_id, timeout=1)

This Method returns a message object for a defined message or None, if this message is not available after the given timout.

Parameters:
  • service_id (int) – The Service-ID for the message. See class definitions starting with SID_.
  • data_id (int) – The Data-ID for the message.
  • timeout (float) – The timeout for receiving.
Returns:

The received data storage object or None, if no data was received.
Return type:

data_storage
reconnect()

This methods initiates a reconnect by calling comm_instance.reconnect().

register_callback(service_id, data_id, callback, *args, **kwargs)

This method registers a callback for the given parameters. Giving None means, that all Service-IDs or all Data-IDs are used. If a message hitting these parameters has been received, the callback will be executed.

Parameters:
  • service_id (int) – The Service-ID for the message. See class definitions starting with SID_.
  • data_id (int) – The Data-ID for the message.

Note

The callback() is priorised in the following order:

  • Callbacks with defined Service-ID and Data-ID.
  • Callbacks with a defined Service-ID and all Data-IDs.
  • Callbacks with a defined Data-ID and all Service-IDs.
  • Unspecific Callbacks.

Note

The callback() is executed with these arguments:

Parameters given at the callback call:

  • The first Arguments is the received message as data_storage object.
  • Further arguments given at registration.
  • Further keyword arguments given at registration.

Return value of the callback:

If the Callback is a Request Callback for a registered Service, the return value has to be a tuple or list with

  • response_status: The response status (see class definitions starting with STA_*.
  • response_data: A JSON iterable object to be used as data for the response.

Note

Only registered services will respond via the callbacks return values with the same data_id.

send(service_id, data_id, data, status=0, timeout=2)

This methods sends out a message with the given content.

Parameters:
  • service_id (int) – The Service-ID for the message. See class definitions starting with SERVICE_.
  • data_id (int) – The Data-ID for the message.
  • data (str) – The data to be transfered. The data needs to be json compatible.
  • status (int) – The Status for the message. All requests should have STATUS_OKAY.
  • timeout (float) – The timeout for sending data (e.g. time to establish new connection).
Returns:

True if data had been sent, otherwise False.
Return type:

bool
class socket_protocol.struct_json_protocol(*args, **kwargs)

This Class has the same functionality like pure_json_protocol. The message length is less than for pure_json_protocol, but the functionality and compatibility is reduced.

Note

This class is depreceated and here for compatibility reasons (to support old clients or servers). Usage of pure_json_protocol is recommended.

Indices and tables