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:

class socket_protocol.data_storage(*args, **kwargs)
Parameters:
  • status (int) – The message status.
  • service_id (int) – The Service-ID.
  • data_id (int) – The Data-ID.
  • data (any) – The transfered data.

This is a storage object for socket_protocol messages.

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

This Method returns the message data.

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

This Method returns the message Data-ID.

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

This Method returns the message Service-ID.

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

This Method returns the message status.

class socket_protocol.pure_json_protocol(comm_instance, secret=None, auto_auth=False, channel_name=None)
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 (True) to enable 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

This class supports to transfer a Service-ID, Data-ID and Data.

  • 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 if needed.
  • 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.
AUTH_STATE_KEY_TRANSFERRED = 3

Authentification Status for ‘Key has been sent’

AUTH_STATE_SEED_REQUESTED = 1

Authentification Status for ‘Seed was requested’

AUTH_STATE_SEED_TRANSFERRED = 2

Authentification Status for ‘Seed has been sent’

AUTH_STATE_TRUSTED_CLIENT = 4

Authentification Status for ‘Trusted Connection’

AUTH_STATE_UNKNOWN_CLIENT = 0

Authentification Status for ‘Unknown Client’

AUTH_STATE__NAMES = {0: 'Unknown Client', 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

SID_AUTH_KEY_CHECK_REQUEST = 3

SID for request for checking a key

SID_AUTH_KEY_CHECK_RESPONSE = 4

SID for the authentification response

SID_AUTH_KEY_REQUEST = 2

SID for requesting a key for the given seed

SID_AUTH_SEED_REQUEST = 1

SID for requesting a seed for authentification

SID_CHANNEL_NAME_REQUEST = 5

SID for requesting a channel name exchange

SID_CHANNEL_NAME_RESPONSE = 6

SID for the channel name response

SID_EXECUTE_REQUEST = 30

SID for a execute request

SID_EXECUTE_RESPONSE = 31

SID for a execute response

SID_READ_REQUEST = 10

SID for a read data request

SID_READ_RESPONSE = 11

SID for read data response

SID_WRITE_REQUEST = 20

SID for a write data request

SID_WRITE_RESPONSE = 21

SID for a write data response

SID__NO_AUTH_LIST = [1, 2, 3, 4, 5, 6]

List of SIDs without need of an authentification

SID__RESPONSE_DICT = {1: 2, 2: 3, 3: 4, 5: 6, 10: 11, 20: 21, 30: 31}

Dictionary to get the SID for the response by the key which is the SID for the request

STATUS_AUTH_REQUIRED = 2

Status for ‘authentification is required’

STATUS_BUFFERING_UNHANDLED_REQUEST = 1

Status for ‘unhandled request’

STATUS_CHECKSUM_ERROR = 4

Status for ‘checksum error’

STATUS_OKAY = 0

Status for ‘okay’

STATUS_OPERATION_NOT_PERMITTED = 5

Status for ‘operation not permitted’

STATUS_SERVICE_OR_DATA_UNKNOWN = 3

Status for ‘service or data unknown’

STATUS__NAMES = {0: 'Okay', 1: 'Request has no callback. Data buffered.', 2: 'Authentification required', 3: 'Service or Data unknown', 4: 'Checksum Error', 5: 'Operation not permitted'}

Status names for previous defined states

authentificate(timeout=2)
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

This method authetificates the client at the server.

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()
Returns:True, if authentification state is okay, otherwise False
Return type:bool
connection_established()
Returns:True, if the connection is established (incl. authentification, if a secret has been given)
Return type:bool
is_connected()
Returns:True if the comm_instance is connected, otherwise False..
Return type:bool

This methods returns the return value of comm_instance.is_connected().

receive(service_id, data_id, timeout=1)
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)
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.
Returns:

True, if registration was successfull; False, if registration failed (e.g. existance of a callback for this configuration)
Return type:

bool

This method registers a callback for the given parameters. Givin 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.

Note

The callback() is priorised in the following order:

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

Note

The callback() is executed with these arguments:

param msg:A data_storage object containing all message information.
returns:(status, response_data)
  • status: A status as defined as a constant of this class STA_* to be used as status for the response.
  • response_data: A JSON iterable object to be used as data for the response.

Note

Only callbacks defined in pure_json_protocol.SID__RESPONSE_DICT will send a response, using a Service-ID given in the dict and the same Data-ID to the client.

send(service_id, data_id, data, status=0, timeout=2, log_lvl=20)
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).
  • rx_log_lvl (int) – The log level to log outgoing TX-data
Returns:

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

bool

This methods sends out a message with the given content.

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