Class isds_ctx

Class isds_ctx

class isds.isds_ctx

This class holds the communication context.

Note that after logging in to the ISDS server the server will shut the connection after a period of inactivity. You may use a timer which will periodically call isds_ctx.ping() to keep the connection alive.

The isds_ctx does not provide any means of thread safety. If you want to share a single isds_ctx instance between multiple threads then you have to explicitly protect it against simultaneous access.

find_box(criteria)

Find boxes suiting given criteria.

Parameters:criteria (isds_db_owner_info) –

Filter criteria, You should fill in at least some members. Following entries are ignored:

Returns:Tuple containing (isds_error, list of isds_db_owner_info). Returns None instead of list on error. Usual return codes are:
  • IE_SUCCESS - Search succeeded.
  • IE_NOEXIST - Data box does not exist.
  • IE_2BIG - Too many matching boxes exist. Server truncated the results. Resulting list contains valid data.
find_box_fulltext(query, target, box_type, page_size, page_number, track_matches)

Find boxes matching a given full-text criteria.

Parameters:
  • query (string) – A non-empty string which consists a phrase to search for.
  • target (isds_fulltext_target) – Selects box attributes to search for query words. Pass None if you don’t care.
  • box_type (isds_pki_format) –

    Restricts searching to given box type. Values have the following meaning:

    • DBTYPE_SYSTEM - Search in all box types.

    Pass None to let server to use default value which is DBTYPE_SYSTEM.

  • page_size (int) – Defines the count of boxes to constitute a response page. It counts from zero. Pass None to let the server to use a default value.
  • page_number (int) – Defines ordinary number of the response page to return. It counts from zero. Pass None to let the server to use a default value.
  • track_matches (bool) – True for marking query words found in the box attributes, False for not marking. Pass None to let the server to use default value.
Returns:

Tuple containing (isds_error, isds_fulltext_result_meta). Returns None instead of isds_fulltext_result_meta on error. Usual return codes are:

  • IE_SUCCESS - Search succeeded.
  • IE_2BIG - If page_size is too large.

get_message_sender(dmID)

Download information about the message author.

Parameters:dmID (string) – Message identifier (see isds_envelope.dmID).
Returns:Tuple containing (isds_error, isds_message_author). Returns None instead of isds_message_author on error.
get_received_messages(from_time, to_time, dmRecipientOrgUnitNum, message_status_filter, offset, max_num)

Get list of received messages.

Parameters:
  • from_time (isds_time) – Minimum time of message sending inclusive. Pass None if you don’t care.
  • to_time (isds_time) – Maximum time of message sending inclusive. Pass None if you don’t care.
  • dmSenderOrgUnitNum (int) – Recipient organisation unit as defined in isds_envelope. Pass None if you don’t care.
  • message_status_filter (int) – Specifies status of the messages you want to download. Use bit operations to select between desired values from isds_message_status:
  • offset (int) – Index of the first message in the sequence. First message has the index 1. Use 0 or 1 if you want to download all messages.
  • max_num (int) – Specifies the maximum length of the list you want to get. Pass None if you don’t care.
Returns:

Tuple containing (isds_error, list of isds_message). Returns None instead of list on error.

get_sent_messages(from_time, to_time, dmSenderOrgUnitNum, message_status_filter, offset, max_num)

Get list of sent messages.

Parameters:
  • from_time (isds_time) – Minimum time of message sending inclusive. Pass None if you don’t care.
  • to_time (isds_time) – Maximum time of message sending inclusive. Pass None if you don’t care.
  • dmSenderOrgUnitNum (int) – Sender organisation unit as defined in isds_envelope. Pass None if you don’t care.
  • message_status_filter (int) – Specifies status of the messages you want to download. Use bit operations to select between desired values from isds_message_status.
  • offset (int) – Index of the first message in the sequence. First message has the index 1. Use 0 or 1 if you want to download all messages.
  • max_num (int) – Specifies the maximum length of the list you want to get. Pass None if you don’t care.
Returns:

Tuple containing (isds_error, list of isds_message). Returns None instead of list on error.

get_signed_delivery_info(dmID)

Download signed delivery info.

Note:The obtained isds_message will miss isds_message.documents. Use isds_ctx.get_signed_sent_message() or isds_ctx.get_signed_received_message() if you are interested in the documents (i.e. message attachments). On the other hand only this method can get the event list which the message has gone through.
Parameters:dmID (string) – Message identifier (see isds_envelope.dmID). You can use isds_ctx.get_sent_messages() or isds_ctx.get_received_messages() to obtain a list of message identifiers.
Returns:Tuple containing (isds_error, isds_message). Returns None instead of isds_message on error.
get_signed_received_message(dmID)

Download signed received message.

Note:The isds_message.raw of the returned isds_message will be filled with PKCS#7 data in DER format.
Parameters:dmID (string) – Message identifier (see isds_envelope.dmID). You can use isds_ctx.get_received_messages() to obtain a list of message identifiers.
Returns:Tuple containing (isds_error, isds_message). Returns None instead of isds_message on error.
get_signed_sent_message(dmID)

Download signed sent message.

Note:The isds_message.raw of the returned isds_message will be filled with PKCS#7 data in DER format.
Parameters:dmID (string) – Message identifier (see isds_envelope.dmID). You can use isds_ctx.get_sent_messages() to obtain a list of message identifiers.
Returns:Tuple containing (isds_error, isds_message). Returns None instead of isds_message on error.
guess_raw_type(raw)

Determine type of raw message or delivery info according some heuristics.

Note:It does not validate the raw blob.
Parameters:raw (bytes, bytearray) – Raw message or delivery info data.
Returns:Tuple containing (isds_error, isds_raw_type). Returns None instead of isds_raw_type on error.
load_delivery_info(raw_type, raw)

Load delivery info of given format.

Parameters:
  • raw_type (isds_raw_type) – Advertises format of raw content. Only delivery info types are accepted.
  • raw (bytes, bytearray) – Raw delivery info data.
Returns:

Tuple containing (isds_error, isds_message). Returns None instead of isds_message on error.

load_message(raw_type, raw)

Load message of given format.

Parameters:
  • raw_type (isds_raw_type) – Advertises format of raw content. Only message types are accepted.
  • raw (bytes, bytearray) – Raw message data.
Returns:

Tuple containing (isds_error, isds_message). Returns None instead of isds_message on error.

login_cert(username, password=None, engine=None, cert_format=0, cert=None, key_format=0, key=None, passphrase=None, test_env=False)

Connect and log in to the ISDS server using the supplied username, password and certificate data.

Parameters:
  • username (string) – User login name.
  • password (string) – User password. You don’t have to supply the password if the account just uses the certificate to log in.
  • engine (string) – String identifier of cryptographic engine to use (i.e. where key is stored).
  • cert_format (isds_pki_format) – Certificate format.
  • cert (string) – Path to client certificate (or certificate nickname in case of NSS as curl back-end) or key slot identifier inside cryptographic engine. Some cryptographic engines can pair certificates with keys automatically (None value).
  • key_format (isds_pki_format) – Private key format.
  • key – Path to client private key, or key identifier in case of used engine.
  • key – string
  • passphrase (string) – String with password for private key decryption or engine PIN. Use None for no pass-phrase or to be questioned by the underlying engine.
  • test_env (bool) – False if connecting to production environment, True if connecting to testing environment.
Returns:

(isds_error) Error state.

login_hotp(username, password, hotp_code, test_env=False)

Connect and log in to the ISDS server using the supplied username, password and HMAC-based OTP method code.

Parameters:
  • username (string) – User login name.
  • password (string) – User password.
  • hotp_code (string) – HMAC-based OTP code.
  • test_env (bool) – False if connecting to production environment, True if connecting to testing environment.
Returns:

Tuple containing (isds_error, isds_otp_resolution).

login_pwd(username, password, test_env=False)

Connect and log in to the ISDS server using the supplied username and password.

Parameters:
  • username (string) – User login name.
  • password (string) – User password.
  • test_env (bool) – False if connecting to production environment, True if connecting to testing environment.
Returns:

(isds_error) Error state.

login_totp(username, password, totp_code, test_env=False)

Connect and log in to the ISDS server using the supplied username, password and time-based OTP method code (SMS code).

Parameters:
  • username (string) – User login name.
  • password (string) – User password.
  • totp_code (string) – Time-based OTP code. Use None to request a new SMS code from ISDS.
  • test_env (bool) – False if connecting to production environment, True if connecting to testing environment.
Returns:

Tuple containing (isds_error, isds_otp_resolution). The returned isds_error usually contains:

  • IE_SUCCESS - Authentication succeeded.
  • IE_NOT_LOGGED_IN - Authentication failed. Fine-grade status can be obtained from isds_otp_resolution. Error message from server can be obtained using isds_ctx.long_message().
  • IE_PARTIAL_SUCCESS - Time-based OTP authentication has been requested and the server has sent the OTP code through a side channel. The application is expected to fill-in the obtained code into totp_code. Keep other arguments unchanged and retry this call to complete the second phase of the TOTP authentication.

logout()

Log out from ISDS and close connection.

Returns:(isds_error) Error state.
long_message()

Return long message text produced by the library (e.g. detailed error message).

Returns:(string) Error message.
ping()

Test whether connection to ISDS is alive. Sends a dummy request and expects a dummy response.

Returns:(isds_error) Error state.
send_message(message)

Send message.

Parameters:message (isds_message) – Message to be sent. Some members (e.g. dbIDRecipient) are mandatory, some are optional an some are ignored (e.g. data about the sender.) The document list must contain al least one document of the type FILEMETATYPE_MAIN.
Throws TypeError:
 When message of non-isds_message type.
Returns:Tuple containing (isds_error, dmID). Returns None instead of dmID on error.
set_timeout(timeout_ms)

Sets timeout in ms. This value applies for every network-related operation (e.g. connecting to the server or sending a message). Use 0 to disable the timeout limit.

Parameters:timeout_ms (int) – Timeout in ms.