IPPhone Class

Properties   Methods   Events   Config Settings   Errors  

The IPPhone class can be used to implement a software-based phone.

Syntax

class ipworksvoip.IPPhone

Remarks

The IPPhone class can be used to implement a software-based phone utilizing modern Voice over Internet Protocol (VoIP) technology. This softphone is able to perform many different functions of a traditional telephone, such as making and receiving calls, performing blind and attended transfers, placing calls on hold, establishing and joining conferences, and more.

Registration

To begin, the first step is activating, or registering, the class. The server, port, user, and password properties must be set to the appropriate values to register with your SIP server/provider. After these values are set, call activate. If the class has successfully activated/registered, the on_activated event will fire and active will be set to true. The class will now be able to make/receive phone calls. For example:

component.OnActivated += (o, e) => { Console.WriteLine("Activation Successful"); }; component.User = "sip_user"; component.Password = "sip_password"; component.Server = "sip_server"; component.Port = 5060 // Default, 5061 is typical for SSL/TLS component.Activate(); Additionally, it's important to note that the registration of a SIP client will expire if not refreshed. The expiration time is negotiated with the server when registering. By default, the class will attempt to negotiate a value of 60 seconds. This value can be changed via the RegistrationInterval configuration. Note this is merely a suggestion to the server, and the server can change this accordingly. If the server does change this, RegistrationInterval will be updated after successful registration. By default, the class will attempt to refresh the registration every RegistrationInterval seconds.

Clients may wish to refresh the registration a few seconds prior to this interval to ensure the registration does not expire. To do so, the RefreshInterval configuration can be set after successful registration. If set, this value should be less than or equal to RegistrationInterval. For example, to refresh the registration 5 seconds prior to it's expiration, the following can be performed after activation:

component.Activate(); int lifetime = component.Config("RegistrationInterval"); // Refresh the registration 5 seconds prior to expiration component.Config("RefreshInterval=" + (lifetime - 5));

To prevent the registration from expiring, the class will refresh the registration within do_events according to the value of RegistrationInterval or RefreshInterval. To ensure this occurs, we recommend calling do_events frequently. For example, this could look something like:

private void timer1_Tick(object sender, EventArgs e) { component.DoEvents(); } private System.Windows.Forms.Timer timer1; timer1.Interval = 1000; timer1.Tick += new System.EventHandler(this.timer1_Tick); timer1.Enabled = true;

Note the above solution does not apply to console applications, as do_events should already be called in a loop to provide efficient message processing.

Security

By default, the class operates in plaintext for both SIP signaling and RTP (audio) communication. To enable completely secure communication using the class, both SIPS (Secure SIP) and SRTP (Secure RTP) must be enabled.

Enable SIPS

To enable SIPS (Secure SIP, or SIP over SSL/TLS), the sip_transport_protocol property must be set to 2 (TLS). The port property will typically need to be set to 5061 (this may vary). Additionally, the on_ssl_server_authentication event must be handled, allowing users to check the server identity and other security attributes related to server authentication. Once this is complete, the class can then be activated. All subsequent SIP signaling will now be secured. For example:

component.OnSSLServerAuthentication += (o, e) => { if (!e.Accept) { if (e.CertSubject == "SIPS_SAMPLE_SUBJECT" && e.CertIssuer == "SIPS_CERT_ISSUER") { e.Accept = true; } } }; // Enable SIPS component.SIPTransportProtocol = 2; // TLS component.User = "sip_user"; component.Password = "sip_password"; component.Server = "sip_server"; component.Port = 5061; // 5061 is typical for SSL/TLS component.Activate();

Information related to the SSL/TLS handshake will be available within the on_ssl_status event with the prefix [SIP TLS].

Enable SRTP

While the above process secures SIP signaling, it does not secure RTP (audio) communication. The rtp_security_mode property can be used to specify the security mode that will be used when transmitting RTP packets. By default, this property is 0 (None), and RTP packets will remain unencrypted during communication with the remote party.

To ensure the audio data is encrypted and SRTP is enabled, the rtp_security_mode must be set to either of the following modes: 1 (SDES), or 2 (DTLS-SRTP). The selected mode will be used to securely derive a key used to encrypt and decrypt RTP packets, enabling secure audio communication with the remote party. The appropriate mode to use may depend on the service provider and configuration of a particular user. For example:

component.OnSSLServerAuthentication += (o, e) => { if (!e.Accept) { if (e.CertSubject == "SIPS_SAMPLE_SUBJECT" && e.CertIssuer == "SIPS_CERT_ISSUER") { e.Accept = true; } } }; component.RTPSecurityMode = 1; // Enable SRTP (SDES) //component.RTPSecurityMode = 2; // Enable SRTP (DTLS-SRTP) component.SIPTransportProtocol = 2; // TLS component.User = "sip_user"; component.Password = "sip_password"; component.Server = "sip_server"; component.Port = 5061; // 5061 is typical for SSL/TLS component.Activate(); component.Dial("123456789", "", true);

Note it is highly recommended that sip_transport_protocol is set to TLS when enabling SRTP. Additionally, if SRTP is enabled, the remote party must support the selected mode, otherwise no call will be established.

Audio Setup

While not required to function, you may set the microphone and speaker for the class to use during calls. First, you must call list_microphones and list_speakers. Doing so will populate the Microphone* properties and the Speaker* properties. Once this is done, you can set these devices via set_microphone and set_speaker given their device name. For example:

ipphone1.ListMicrophones(); ipphone1.ListSpeakers(); foreach (Speaker s in ipphone1.Speakers) { Console.WriteLine("Speaker Name: " + s.Name); } foreach (Microphone m in ipphone1.Microphones) { Console.WriteLine("Microphone Name: " + m.Name); } ipphone1.SetSpeaker(ipphone1.Speakers[0].Name); ipphone1.SetMicrophone(ipphone1.Microphones[0].Name);

Managing Calls

All incoming and outgoing calls currently recognized by the class will be stored in the Call* properties. These connections will be initiated or accepted through the interface identified by local_host and local_port.

Incoming Calls

After successful activation, incoming calls will be detected, and on_incoming_call will fire for each call. Within this event, answer, decline, or forward can be used to handle these calls. For example:

ipphone1.OnIncomingCall += (o, e) => { ipphone1.Answer(e.CallId); };

Outgoing Calls

To make an outgoing call, you must use dial. This method takes three parameters: the user you wish to call, your caller ID (optional), and a boolean that determines whether the method will connect synchronously (True) or asynchronously (False). If set, the second parameter will cause P-Asserted-Identity headers (RFC 3325) to be sent in requests to the server. If left as an empty string, this header will not be sent. dial will return a call identification string (CallId) that is unique to the call. After the method returns successfully, the call will be added to the Call* properties.

Please see the method description for detailed examples on using dial synchronously and asynchronously.

Transferring Calls

Ongoing calls can be transferred using transfer. The class supports two types of transfers:

Basic (Blind) Transfers

Basic transfers are very simple to perform. First, the user establishes a call with the number they will be transferring (transferee). After the call is established, the user can transfer the call to the appropriate number (transfer target). The call will then be removed. For example:

string callId = ipphone1.Dial("123456789", "", true); // Establish call with transferee, hold if needed //ipphone1.Hold(callId); ipphone1.Transfer(callId, "number");

Attended Transfers

Typically, attended transfers are used to manually check if the "number" they are transferring to (transfer target) is available for a call, provide extra information about the call, etc., before transferring. In addition to establishing a call with the transferee, the class must also establish a call with the transfer target. Once both calls are active, you may perform an attended transfer by calling transfer at any moment. Afterwards, a session will be established between both calls, and they will be removed. Note that transfer must be used with the CallId of the call you wish to transfer (transferee) and the Number of the call you wish to transfer to (transfer target). For example:

string callId1 = ipphone1.Dial("123456789", "", true); // Establish call with Transferee, hold if needed //ipphone1.Hold(callId1); string callId2 = ipphone1.Dial("number", "", true); // Establish call with Transfer Target, hold if needed //ipphone1.Hold(callId2); ipphone1.Transfer(callId1, "number");

Note in these examples, hold can be used to place a call on hold before a transfer. This is optional.

Audio Playback

The class supports three methods of playing audio to a call, being play_file, play_text, or play_bytes. Note for each of these methods, audio transmission will only occur when the call has connected and on_call_ready has fired. Additionally, only audio data with a sampling rate of 8 kHz and a bit depth of 16 bits per sample can be played (PCM 8 kHz 16-bit format). Also note that these methods are non-blocking, and will return immediately. The class can also handle playing audio to concurrent calls.

play_file can be used to play audio from a WAV file to a specific call. play_text can also be used to play audio, but will do so using Text-to-Speech. Once audio has finished playing, on_played will fire.

play_bytes can be used to play audio, but will do so in an event-based manner. The behavior of play_bytes is very different from the previous two methods. For a detailed description on how to use this method with the on_played event, please see the method and event descriptions.

Recording Audio

Ongoing calls can be recorded using start_recording. The audio can be recorded directly to a WAV file by specifying the Filename parameter. Additionally, if the Filename parameter is not specified, the audio will be recorded internally, and made available once the recording is finished. The recorded data will be available within the on_record event.

Note in both scenarios, the recording will end either when the call is terminated, or stop_recording is called. The recorded audio will have a sampling rate of 8 kHz and a bit depth of 16 bits per sample (PCM 8 kHz 16-bit format).

Example: Using the 'Record' event

MemoryStream recordStream = new MemoryStream(); phone.StartRecording("CallId", ""); phone.OnRecord += (o, e) => { recordStream.Write(e.RecordedDataB, 0, e.RecordedDataB.Length); File.WriteAllBytes(recordFile, recordStream.ToArray()); };

Conferencing

The class also supports conferencing. A call can join a conference using the join_conference method, passing in the CallId of the call and the custom ConferenceId. If the ConferenceId does not exist, then a new conference will be created given this ID. Other calls can then join the existing conference with this same ID.

To monitor existing conferences, the list_conferences method will return a string containing all ongoing conferences and calls within each conference. This value will have the following format:

ConferenceId_1: CallId_1, CallId_2

...

ConferenceId_n: CallId_3, CallId_4, CallId_5, ...

At any moment, a call can be removed from a conference using leave_conference. If the user is the last call within the conference, then the conference will be removed.

Call Termination

Ongoing calls are terminated by passing the appropriate CallId to hangup. All ongoing calls can be terminated with hangup_all. When a call has been terminated (by either party), on_call_terminated will fire. It's important to note that in the case where an outgoing call is never answered, the class will attempt to leave a voicemail. The voicemail will end once hangup or hangup_all is called, and on_call_terminated will fire.

Property List


The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

activeThe current activation status of the class.
call_countThe number of records in the Call arrays.
call_call_idString representation of an immutable universally unique identifier (UUID) specific to the call.
call_conference_idA unique identifier for a conference call.
call_durationElapsed time, in seconds, since the call has begun.
call_last_statusThis property indicates the call's last response code.
call_local_addressThe name of the local host or user-assigned IP interface through which connections are initiated or accepted.
call_local_portThe UDP port in the local host where UDP binds.
call_microphoneThe microphone currently in use during the call.
call_mute_microphoneThis property can be set to mute the Microphone being used by the class in the given call.
call_mute_speakerThis property can be set to mute the Speaker being used by the class in the given call.
call_outgoingIndicates whether the current call is outgoing.
call_playingIndicates whether the current call is playing audio via PlayText or PlayFile , or PlayBytes .
call_recordingIndicates whether the current call is recording the received voice from the peer.
call_remote_addressThe address of the remote host we are communicating with.
call_remote_portThe port of the remote host we are communicating with.
call_remote_uriThis property communicates who to call via SIP.
call_remote_userThe username or telephone number of the remote user associated with the call.
call_speakerThe speaker currently in use during the call.
call_started_atThe number of milliseconds since 12:00:00 AM January 1, 1970 when this call started.
call_stateThis property indicates the state of the current call.
call_user_inputString representation of digits typed by the callee using their keypad.
call_viaThe Via header sent in the most recent SIP request.
local_hostThis property includes the name of the local host or user-assigned IP interface through which connections are initiated or accepted.
local_portThis property includes the User Datagram Protocol (UDP) port in the local host where UDP binds.
microphone_countThe number of records in the Microphone arrays.
microphone_channelsNumber specifying whether the device supports mono (1) or stereo (2) output.
microphone_manufacturer_idManufacturer identifier for the device driver for the device.
microphone_nameProduct name in a null-terminated string.
microphone_product_idProduct identifier for the device as assigned by Windows.
microphone_supportBitmask of optional functionalities supported by the device.
microphone_supported_formatsBitmask of standard formats that are supported.
passwordThe password that is used when connecting to the SIP Server.
portThe port on the SIP server the class is connecting to.
rtp_security_modeSpecifies the security mode that will be used when transmitting RTP.
serverThe address of the SIP Server.
sip_transport_protocolSpecifies the transport protocol the class will use for SIP signaling.
speaker_countThe number of records in the Speaker arrays.
speaker_channelsNumber specifying whether the device supports mono (1) or stereo (2) output.
speaker_manufacturer_idManufacturer identifier for the device driver for the device.
speaker_nameProduct name in a null-terminated string.
speaker_product_idProduct identifier for the device as assigned by Windows.
speaker_supportBitmask of optional functionalities supported by the device.
speaker_supported_formatsBitmask of standard formats that are supported.
ssl_accept_server_cert_effective_dateThis is the date on which this certificate becomes valid.
ssl_accept_server_cert_expiration_dateThis is the date the certificate expires.
ssl_accept_server_cert_extended_key_usageThis is a comma-delimited list of extended key usage identifiers.
ssl_accept_server_cert_fingerprintThis is the hex-encoded, 16-byte MD5 fingerprint of the certificate.
ssl_accept_server_cert_fingerprint_sha1This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate.
ssl_accept_server_cert_fingerprint_sha256This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate.
ssl_accept_server_cert_issuerThis is the issuer of the certificate.
ssl_accept_server_cert_private_keyThis is the private key of the certificate (if available).
ssl_accept_server_cert_private_key_availableThis property shows whether a PrivateKey is available for the selected certificate.
ssl_accept_server_cert_private_key_containerThis is the name of the PrivateKey container for the certificate (if available).
ssl_accept_server_cert_public_keyThis is the public key of the certificate.
ssl_accept_server_cert_public_key_algorithmThis property contains the textual description of the certificate's public key algorithm.
ssl_accept_server_cert_public_key_lengthThis is the length of the certificate's public key (in bits).
ssl_accept_server_cert_serial_numberThis is the serial number of the certificate encoded as a string.
ssl_accept_server_cert_signature_algorithmThe property contains the text description of the certificate's signature algorithm.
ssl_accept_server_cert_storeThis is the name of the certificate store for the client certificate.
ssl_accept_server_cert_store_passwordIf the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.
ssl_accept_server_cert_store_typeThis is the type of certificate store for this certificate.
ssl_accept_server_cert_subject_alt_namesThis property contains comma-separated lists of alternative subject names for the certificate.
ssl_accept_server_cert_thumbprint_md5This property contains the MD5 hash of the certificate.
ssl_accept_server_cert_thumbprint_sha1This property contains the SHA-1 hash of the certificate.
ssl_accept_server_cert_thumbprint_sha256This property contains the SHA-256 hash of the certificate.
ssl_accept_server_cert_usageThis property contains the text description of UsageFlags .
ssl_accept_server_cert_usage_flagsThis property contains the flags that show intended use for the certificate.
ssl_accept_server_cert_versionThis property contains the certificate's version number.
ssl_accept_server_cert_subjectThis is the subject of the certificate used for client authentication.
ssl_accept_server_cert_encodedThis is the certificate (PEM/Base64 encoded).
ssl_cert_effective_dateThis is the date on which this certificate becomes valid.
ssl_cert_expiration_dateThis is the date the certificate expires.
ssl_cert_extended_key_usageThis is a comma-delimited list of extended key usage identifiers.
ssl_cert_fingerprintThis is the hex-encoded, 16-byte MD5 fingerprint of the certificate.
ssl_cert_fingerprint_sha1This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate.
ssl_cert_fingerprint_sha256This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate.
ssl_cert_issuerThis is the issuer of the certificate.
ssl_cert_private_keyThis is the private key of the certificate (if available).
ssl_cert_private_key_availableThis property shows whether a PrivateKey is available for the selected certificate.
ssl_cert_private_key_containerThis is the name of the PrivateKey container for the certificate (if available).
ssl_cert_public_keyThis is the public key of the certificate.
ssl_cert_public_key_algorithmThis property contains the textual description of the certificate's public key algorithm.
ssl_cert_public_key_lengthThis is the length of the certificate's public key (in bits).
ssl_cert_serial_numberThis is the serial number of the certificate encoded as a string.
ssl_cert_signature_algorithmThe property contains the text description of the certificate's signature algorithm.
ssl_cert_storeThis is the name of the certificate store for the client certificate.
ssl_cert_store_passwordIf the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.
ssl_cert_store_typeThis is the type of certificate store for this certificate.
ssl_cert_subject_alt_namesThis property contains comma-separated lists of alternative subject names for the certificate.
ssl_cert_thumbprint_md5This property contains the MD5 hash of the certificate.
ssl_cert_thumbprint_sha1This property contains the SHA-1 hash of the certificate.
ssl_cert_thumbprint_sha256This property contains the SHA-256 hash of the certificate.
ssl_cert_usageThis property contains the text description of UsageFlags .
ssl_cert_usage_flagsThis property contains the flags that show intended use for the certificate.
ssl_cert_versionThis property contains the certificate's version number.
ssl_cert_subjectThis is the subject of the certificate used for client authentication.
ssl_cert_encodedThis is the certificate (PEM/Base64 encoded).
userThe username that is used when connecting to the SIP Server.

Method List


The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

activateActivates the class.
answerAnswers an incoming phone call.
configSets or retrieves a configuration setting.
deactivateDeactivates the class.
declineDeclines an incoming phone call.
dialUsed to make a call.
do_eventsThis method processes events from the internal message queue.
forwardUsed to forward an incoming call.
hangupUsed to hang up a specific call.
hangup_allUsed to hang up all calls.
holdPlaces a call on hold.
join_conferenceAdds a call to a conference call.
leave_conferenceRemoves a call from a conference call.
list_conferencesLists ongoing conference calls.
list_microphonesLists all microphones detected on the system.
list_speakersLists all speakers detected on the system.
mute_microphoneUsed to mute or unmute the microphone for a specified call.
mute_speakerUsed to mute or unmute the speaker for a specified call.
pingUsed to ping the server.
play_bytesThis method is used to play bytes to a call.
play_filePlays audio from a WAV file to a call.
play_textPlays audio from a string to a call using Text-to-Speech.
resetThis method will reset the class.
set_microphoneSets the microphone used by the class.
set_speakerSets the speaker used by the class.
start_recordingUsed to start recording the audio of a call.
stop_playingStops audio from playing to a call.
stop_recordingStops recording the audio of a call.
transferTransfers a call.
type_digitUsed to type a digit.
unholdTakes a call off hold.

Event List


The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

on_activatedThis event is fired immediately after the class is activated.
on_call_readyThis event is fired after a call has been answered, declined, or ignored.
on_call_state_changedThis event is fired after a call's state has changed.
on_call_terminatedThis event is fired after a call has been terminated.
on_deactivatedThis event is fired immediately after the class is deactivated.
on_dial_completedThis event is fired after the dial process has finished.
on_digitThis event fires every time a digit is pressed using the keypad.
on_errorFired when information is available about errors during data delivery.
on_incoming_callThis event is fired when an incoming call is received.
on_logThis event is fired once for each log message.
on_outgoing_callThis event is fired when an outgoing call has been made.
on_playedThis event is fired after the class finishes playing available audio.
on_recordThis event is fired when recorded audio data is available.
on_silenceThis event is fired when the class detects silence from incoming audio streams.
on_ssl_server_authenticationFired after the server presents its certificate to the client.
on_ssl_statusFired when secure connection progress messages are available.

Config Settings


The following is a list of config settings for the class with short descriptions. Click on the links for further details.

AudioDirectionIndicates the direction of available recorded audio when dynamic recording is enabled.
AuthUserSpecifies the username to be used during client authentication.
CodecsComma-separated list of codecs the class can use.
DeclineStatusSpecifies the status to send when declining an incoming call.
DialTimeoutSpecifies the amount of time to wait for a response when making a call.
DialToneFileSpecifies the location of the WAV file to play when making a call.
DisableRegistrationCan be used to disable SIP registration.
DomainCan be used to set the address of the SIP domain.
DtmfMethodThe method used for delivering the signals/tones sent when typing a digit.
EnableDynamicRecordingSpecifies whether dynamic recording is enabled when recording a call.
LogEncodedAudioDataWhether the class will log encoded audio data.
LogLevelThe level of detail that is logged.
LogRTPPacketsWhether the class will log RTP packets.
RecordTypeThe type of recording the class will use.
RedirectLimitThe maximum number of redirects an outgoing call can experience.
RefreshIntervalUsed to manually specify the interval between subsequent registration messages after successful activation.
RegistrationIntervalSpecifies the lifetime of the current registration.
RingtoneFileSpecifies location of a WAV file to play when receiving an incoming call.
SilenceIntervalSpecifies the interval the class uses to detect periods of silence.
STUNPortThe port of the STUN server.
STUNServerThe address of the STUN Server.
UnregisterOnActivateSpecifies whether the class will unregister from the SIP Server before registration.
VoiceIndexThe voice that will be used when playing text.
VoiceRateThe speaking rate of the voice when playing text.
CaptureIPPacketInfoUsed to capture the packet information.
DelayHostResolutionWhether the hostname is resolved when RemoteHost is set.
DestinationAddressUsed to get the destination address from the packet information.
DontFragmentUsed to set the Don't Fragment flag of outgoing packets.
LocalHostThe name of the local host through which connections are initiated or accepted.
LocalPortThe port in the local host where the class binds.
MaxPacketSizeThe maximum length of the packets that can be received.
QOSDSCPValueUsed to specify an arbitrary QOS/DSCP setting (optional).
QOSTrafficTypeUsed to specify QOS/DSCP settings (optional).
ShareLocalPortIf set to True, allows more than one instance of the class to be active on the same local port.
SourceIPAddressUsed to set the source IP address used when sending a packet.
SourceMacAddressUsed to set the source MAC address used when sending a packet.
UseConnectionDetermines whether to use a connected socket.
UseIPv6Whether or not to use IPv6.
AbsoluteTimeoutDetermines whether timeouts are inactivity timeouts or absolute timeouts.
AbsoluteTimeoutDetermines whether timeouts are inactivity timeouts or absolute timeouts.
FirewallDataUsed to send extra data to the firewall.
FirewallDataUsed to send extra data to the firewall.
InBufferSizeThe size in bytes of the incoming queue of the socket.
InBufferSizeThe size in bytes of the incoming queue of the socket.
OutBufferSizeThe size in bytes of the outgoing queue of the socket.
OutBufferSizeThe size in bytes of the outgoing queue of the socket.
ConnectionTimeoutSets a separate timeout value for establishing a connection.
FirewallAutoDetectTells the class whether or not to automatically detect and use firewall system settings, if available.
FirewallHostName or IP address of firewall (optional).
FirewallPasswordPassword to be used if authentication is to be used when connecting through the firewall.
FirewallPortThe TCP port for the FirewallHost;.
FirewallTypeDetermines the type of firewall to connect through.
FirewallUserA user name if authentication is to be used connecting through a firewall.
KeepAliveIntervalThe retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.
KeepAliveTimeThe inactivity time in milliseconds before a TCP keep-alive packet is sent.
LingerWhen set to True, connections are terminated gracefully.
LingerTimeTime in seconds to have the connection linger.
LocalHostThe name of the local host through which connections are initiated or accepted.
LocalPortThe port in the local host where the class binds.
MaxLineLengthThe maximum amount of data to accumulate when no EOL is found.
MaxTransferRateThe transfer rate limit in bytes per second.
ProxyExceptionsListA semicolon separated list of hosts and IPs to bypass when using a proxy.
TCPKeepAliveDetermines whether or not the keep alive socket option is enabled.
TcpNoDelayWhether or not to delay when sending packets.
UseIPv6Whether to use IPv6.
LogSSLPacketsControls whether SSL packets are logged when using the internal security API.
OpenSSLCADirThe path to a directory containing CA certificates.
OpenSSLCAFileName of the file containing the list of CA's trusted by your application.
OpenSSLCipherListA string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedDataThe data to seed the pseudo random number generator (PRNG).
ReuseSSLSessionDetermines if the SSL session is reused.
SSLCACertFilePathsThe paths to CA certificate files on Unix/Linux.
SSLCACertsA newline separated list of CA certificate to be included when performing an SSL handshake.
SSLCheckCRLWhether to check the Certificate Revocation List for the server certificate.
SSLCheckOCSPWhether to use OCSP to check the status of the server certificate.
SSLCipherStrengthThe minimum cipher strength used for bulk encryption.
SSLClientCACertsA newline separated list of CA certificates to use during SSL client certificate validation.
SSLEnabledCipherSuitesThe cipher suite to be used in an SSL negotiation.
SSLEnabledProtocolsUsed to enable/disable the supported security protocols.
SSLEnableRenegotiationWhether the renegotiation_info SSL extension is supported.
SSLIncludeCertChainWhether the entire certificate chain is included in the SSLServerAuthentication event.
SSLKeyLogFileThe location of a file where per-session secrets are written for debugging purposes.
SSLNegotiatedCipherReturns the negotiated cipher suite.
SSLNegotiatedCipherStrengthReturns the negotiated cipher suite strength.
SSLNegotiatedCipherSuiteReturns the negotiated cipher suite.
SSLNegotiatedKeyExchangeReturns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchangeStrengthReturns the negotiated key exchange algorithm strength.
SSLNegotiatedVersionReturns the negotiated protocol version.
SSLSecurityFlagsFlags that control certificate verification.
SSLServerCACertsA newline separated list of CA certificates to use during SSL server certificate validation.
TLS12SignatureAlgorithmsDefines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal.
TLS12SupportedGroupsThe supported groups for ECC.
TLS13KeyShareGroupsThe groups for which to pregenerate key shares.
TLS13SignatureAlgorithmsThe allowed certificate signature algorithms.
TLS13SupportedGroupsThe supported groups for (EC)DHE key exchange.
BuildInfoInformation about the product's build.
CodePageThe system code page used for Unicode to Multibyte translations.
LicenseInfoInformation about the current license.
MaskSensitiveDataWhether sensitive data is masked in log messages.
ProcessIdleEventsWhether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillisThe length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPIWhether or not to use the system security libraries or an internal implementation.

active Property

The current activation status of the class.

Syntax

def get_active() -> bool: ...

active = property(get_active, None)

Default Value

FALSE

Remarks

This property indicates the activation status of the class. active will be True if the class has been successfully activated (registered) with the SIP Server, and False otherwise. If False, the class is not registered and will not be able to make or receive calls.

The class can be activated via activate and deactivated through deactivate.

This property is read-only.

call_count Property

The number of records in the Call arrays.

Syntax

def get_call_count() -> int: ...

call_count = property(get_call_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

The array indices start at 0 and end at call_count - 1.

This property is read-only.

call_call_id Property

String representation of an immutable universally unique identifier (UUID) specific to the call.

Syntax

def get_call_call_id(call_index: int) -> str: ...

Default Value

""

Remarks

String representation of an immutable universally unique identifier (UUID) specific to the call.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_conference_id Property

A unique identifier for a conference call.

Syntax

def get_call_conference_id(call_index: int) -> str: ...

Default Value

""

Remarks

A unique identifier for a conference call.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_duration Property

Elapsed time, in seconds, since the call has begun.

Syntax

def get_call_duration(call_index: int) -> int: ...

Default Value

0

Remarks

Elapsed time, in seconds, since the call has begun. Calculated using the value in call_started_at.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_last_status Property

This property indicates the call's last response code.

Syntax

def get_call_last_status(call_index: int) -> int: ...

Default Value

0

Remarks

This field indicates the call's last response code. Response codes are defined in RFC 3261.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_local_address Property

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

def get_call_local_address(call_index: int) -> str: ...

Default Value

""

Remarks

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_local_port Property

The UDP port in the local host where UDP binds.

Syntax

def get_call_local_port(call_index: int) -> int: ...

Default Value

0

Remarks

The UDP port in the local host where UDP binds.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_microphone Property

The microphone currently in use during the call.

Syntax

def get_call_microphone(call_index: int) -> str: ...

Default Value

""

Remarks

The microphone currently in use during the call. Set through set_microphone.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_mute_microphone Property

This property can be set to mute the Microphone being used by the class in the given call.

Syntax

def get_call_mute_microphone(call_index: int) -> bool: ...
def set_call_mute_microphone(call_index: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

This field can be set to mute the call_microphone being used by the class in the given call. When True, the call_microphone is muted.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

call_mute_speaker Property

This property can be set to mute the Speaker being used by the class in the given call.

Syntax

def get_call_mute_speaker(call_index: int) -> bool: ...
def set_call_mute_speaker(call_index: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

This field can be set to mute the call_speaker being used by the class in the given call. When True, the call_speaker is muted.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

call_outgoing Property

Indicates whether the current call is outgoing.

Syntax

def get_call_outgoing(call_index: int) -> bool: ...

Default Value

FALSE

Remarks

Indicates whether the current call is outgoing. If false, the call is incoming.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_playing Property

Indicates whether the current call is playing audio via PlayText or PlayFile , or PlayBytes .

Syntax

def get_call_playing(call_index: int) -> bool: ...

Default Value

FALSE

Remarks

Indicates whether the current call is playing audio via play_text or play_file, or play_bytes. After audio transmission is complete, or stopped using stop_playing, this flag will be false.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_recording Property

Indicates whether the current call is recording the received voice from the peer.

Syntax

def get_call_recording(call_index: int) -> bool: ...

Default Value

FALSE

Remarks

Indicates whether the current call is recording the received voice from the peer. When the recording is done, this flag will be false. If the recording is stopped via stop_recording, this flag will be false.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_remote_address Property

The address of the remote host we are communicating with.

Syntax

def get_call_remote_address(call_index: int) -> str: ...

Default Value

""

Remarks

The address of the remote host we are communicating with.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_remote_port Property

The port of the remote host we are communicating with.

Syntax

def get_call_remote_port(call_index: int) -> int: ...

Default Value

0

Remarks

The port of the remote host we are communicating with. This field is typically 5060.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_remote_uri Property

This property communicates who to call via SIP.

Syntax

def get_call_remote_uri(call_index: int) -> str: ...

Default Value

""

Remarks

This field communicates who to call via SIP. This value contains the call_remote_user, call_remote_address, and the call_remote_port, and has the following format:

sip:user@host:port

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_remote_user Property

The username or telephone number of the remote user associated with the call.

Syntax

def get_call_remote_user(call_index: int) -> str: ...

Default Value

""

Remarks

The username or telephone number of the remote user associated with the call.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_speaker Property

The speaker currently in use during the call.

Syntax

def get_call_speaker(call_index: int) -> str: ...

Default Value

""

Remarks

The speaker currently in use during the call. Set through set_speaker.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_started_at Property

The number of milliseconds since 12:00:00 AM January 1, 1970 when this call started.

Syntax

def get_call_started_at(call_index: int) -> int: ...

Default Value

0

Remarks

The number of milliseconds since 12:00:00 AM January 1, 1970 when this call started.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_state Property

This property indicates the state of the current call.

Syntax

def get_call_state(call_index: int) -> int: ...

Default Value

0

Remarks

This property indicates the state of the current call. The applicable values are as follows:

csInactive (0)The call is inactive (default setting).
csConnecting (1)The call is establishing a connection to the callee.
csAutConnecting (2)The call is establishing a connection to the callee with authorization credentials.
csRinging (3)The call is ringing.
csActive (4)The call is active.
csActiveInConference (5)The call is active and in a conference.
csDisconnecting (6)The call is disconnecting with the callee.
csAutDisconnecting (7)The call is disconnecting with the callee with authorization credentials.
csHolding (8)The call is currently being placed on hold, but the hold operation has not finished.
csOnHold (9)The call is currently on hold.
csUnholding (10)The call is currently being unheld, but the unhold operation has not finished.
csTransferring (11)The call is currently being transferred.
csAutTransferring (12)The call is currently being transferred with authorization credentials.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_user_input Property

String representation of digits typed by the callee using their keypad.

Syntax

def get_call_user_input(call_index: int) -> str: ...

Default Value

""

Remarks

String representation of digits typed by the callee using their keypad.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

call_via Property

The Via header sent in the most recent SIP request.

Syntax

def get_call_via(call_index: int) -> str: ...

Default Value

""

Remarks

The Via header sent in the most recent SIP request. Identifies the protocol name/version, transport type, IP Address of the User Agent Client, and port of the request.

The call_index parameter specifies the index of the item in the array. The size of the array is controlled by the call_count property.

This property is read-only.

local_host Property

This property includes the name of the local host or user-assigned IP interface through which connections are initiated or accepted.

Syntax

def get_local_host() -> str: ...
def set_local_host(value: str) -> None: ...

local_host = property(get_local_host, set_local_host)

Default Value

""

Remarks

The local_host property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the IP address of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface. It is recommended to provide an IP address rather than a hostname when setting this property to ensure the desired interface is used.

If the class is connected, the local_host property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

Note: local_host is not persistent. You must always set it in code, and never in the property window.

local_port Property

This property includes the User Datagram Protocol (UDP) port in the local host where UDP binds.

Syntax

def get_local_port() -> int: ...
def set_local_port(value: int) -> None: ...

local_port = property(get_local_port, set_local_port)

Default Value

0

Remarks

The local_port property must be set before UDP is activated (active is set to True). This instructs the class to bind to a specific port (or communication endpoint) in the local machine.

Setting it to 0 (default) enables the Transmission Control Protocol (TCP)/IP stack to choose a port at random. The chosen port will be shown by the local_port property after the connection is established.

local_port cannot be changed once the class is active. Any attempt to set the local_port property when the class is active will generate an error.

The local_port property is useful when trying to connect to services that require a trusted port on the client side.

microphone_count Property

The number of records in the Microphone arrays.

Syntax

def get_microphone_count() -> int: ...

microphone_count = property(get_microphone_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

The array indices start at 0 and end at microphone_count - 1.

This property is read-only.

microphone_channels Property

Number specifying whether the device supports mono (1) or stereo (2) output.

Syntax

def get_microphone_channels(microphone_index: int) -> int: ...

Default Value

0

Remarks

Number specifying whether the device supports mono (1) or stereo (2) output.

The microphone_index parameter specifies the index of the item in the array. The size of the array is controlled by the microphone_count property.

This property is read-only.

microphone_manufacturer_id Property

Manufacturer identifier for the device driver for the device.

Syntax

def get_microphone_manufacturer_id(microphone_index: int) -> int: ...

Default Value

0

Remarks

Manufacturer identifier for the device driver for the device.

The microphone_index parameter specifies the index of the item in the array. The size of the array is controlled by the microphone_count property.

This property is read-only.

microphone_name Property

Product name in a null-terminated string.

Syntax

def get_microphone_name(microphone_index: int) -> str: ...

Default Value

""

Remarks

Product name in a null-terminated string.

The microphone_index parameter specifies the index of the item in the array. The size of the array is controlled by the microphone_count property.

This property is read-only.

microphone_product_id Property

Product identifier for the device as assigned by Windows.

Syntax

def get_microphone_product_id(microphone_index: int) -> int: ...

Default Value

0

Remarks

Product identifier for the device as assigned by Windows.

The microphone_index parameter specifies the index of the item in the array. The size of the array is controlled by the microphone_count property.

This property is read-only.

microphone_support Property

Bitmask of optional functionalities supported by the device.

Syntax

def get_microphone_support(microphone_index: int) -> int: ...

Default Value

0

Remarks

Bitmask of optional functionalities supported by the device. This field can have one or more of the following values OR'd together:

BitmaskFlagDescription
0x0001WAVECAPS_PITCHSupports pitch control.
0x0002WAVECAPS_PLAYBACKRATESupports playback rate control.
0x0004WAVECAPS_VOLUMESupports volume control.
0x0008WAVECAPS_LRVOLUMESupports separate left and right volume control.
0x0010WAVECAPS_SYNCThe driver is synchronous and will block while playing a buffer.
0x0020WAVECAPS_SAMPLEACCURATE Returns sample-accurate position information.

The microphone_index parameter specifies the index of the item in the array. The size of the array is controlled by the microphone_count property.

This property is read-only.

microphone_supported_formats Property

Bitmask of standard formats that are supported.

Syntax

def get_microphone_supported_formats(microphone_index: int) -> int: ...

Default Value

0

Remarks

Bitmask of standard formats that are supported. This field can have one or more of the following values OR'd together:

BitmaskFormatDescription
0x00000001WAVE_FORMAT_1M0811.025 kHz, mono, 8-bit
0x00000002WAVE_FORMAT_1S0811.025 kHz, stereo, 8-bit
0x00000004WAVE_FORMAT_1M1611.025 kHz, mono, 16-bit
0x00000008WAVE_FORMAT_1S1611.025 kHz, stereo, 16-bit
0x00000010WAVE_FORMAT_2M0822.05 kHz, mono, 8-bit
0x00000020WAVE_FORMAT_2S0822.05 kHz, stereo, 8-bit
0x00000040WAVE_FORMAT_2M1622.05 kHz, mono, 16-bit
0x00000080WAVE_FORMAT_2S1622.05 kHz, stereo, 16-bit
0x00000100WAVE_FORMAT_4M0844.1 kHz, mono, 8-bit
0x00000200WAVE_FORMAT_4S0844.1 kHz, stereo, 8-bit
0x00000400WAVE_FORMAT_4M1644.1 kHz, mono, 16-bit
0x00000800WAVE_FORMAT_4S1644.1 kHz, stereo, 16-bit
0x00001000WAVE_FORMAT_48M0848 kHz, mono, 8-bit
0x00002000WAVE_FORMAT_48S0848 kHz, stereo, 8-bit
0x00004000WAVE_FORMAT_48M1648 kHz, mono, 16-bit
0x00008000WAVE_FORMAT_48S1648 kHz, stereo, 16-bit
0x00010000WAVE_FORMAT_96M0896 kHz, mono, 8-bit
0x00020000WAVE_FORMAT_96S0896 kHz, stereo, 8-bit
0x00040000WAVE_FORMAT_96M1696 kHz, mono, 16-bit
0x00080000WAVE_FORMAT_96S1696 kHz, stereo, 16-bit

The microphone_index parameter specifies the index of the item in the array. The size of the array is controlled by the microphone_count property.

This property is read-only.

password Property

The password that is used when connecting to the SIP Server.

Syntax

def get_password() -> str: ...
def set_password(value: str) -> None: ...

password = property(get_password, set_password)

Default Value

""

Remarks

This property contains the password of the client attempting to connect to the SIP Server. This value will be used when activating the class via activate.

port Property

The port on the SIP server the class is connecting to.

Syntax

def get_port() -> int: ...
def set_port(value: int) -> None: ...

port = property(get_port, set_port)

Default Value

5060

Remarks

This property specifies the port on the SIP server that the class will connect to. This value will be used when activating the class via activate.

rtp_security_mode Property

Specifies the security mode that will be used when transmitting RTP.

Syntax

def get_rtp_security_mode() -> int: ...
def set_rtp_security_mode(value: int) -> None: ...

rtp_security_mode = property(get_rtp_security_mode, set_rtp_security_mode)

Default Value

0

Remarks

This property is used to specify the security mode that will be used when transmitting RTP (audio data). Possible modes are:

0 (None) SRTP is disabled.
1 (SDES) SRTP is enabled, utilizing SDES.
2 (DTLS) SRTP is enabled, utilizing DTLS (DTLS-SRTP).

By default, the security mode will be 0 (None), and RTP packets will remain unencrypted during communication with the remote party. To enable SRTP (Secure RTP), the security mode must be set to either: 1 (SDES), or 2 (DTLS).

When SRTP is enabled, the selected mode will be used to securely derive a key used to encrypt and decrypt RTP packets, enabling secure audio communication with the remote party. The appropriate mode to use may depend on the service provider and configuration of a particular user. Additionally, if SRTP is enabled, the remote party must support the selected mode, otherwise no call will be established.

Note it is highly recommended that sip_transport_protocol is set to TLS when enabling SRTP.

server Property

The address of the SIP Server.

Syntax

def get_server() -> str: ...
def set_server(value: str) -> None: ...

server = property(get_server, set_server)

Default Value

""

Remarks

This property contains the address of the SIP Server the class will attempt to connect to. This value will be used when activating the class via activate.

sip_transport_protocol Property

Specifies the transport protocol the class will use for SIP signaling.

Syntax

def get_sip_transport_protocol() -> int: ...
def set_sip_transport_protocol(value: int) -> None: ...

sip_transport_protocol = property(get_sip_transport_protocol, set_sip_transport_protocol)

Default Value

0

Remarks

This property specifies which transport protocol (UDP, TCP, TLS) the class will use for SIP signaling and can be used to enable SIPS (Secure SIP). Note it is important to set the sip_transport_protocol property before setting any additional properties and configurations.

This value is 0 (UDP) by default. Possible values are:

0 (UDP - Default)Signaling will be performed over UDP (plaintext).
1 (TCP)Signaling will be performed over TCP (plaintext).
2 (TLS)Signaling will be performed using TLS over TCP (SIPS).

Note when TLS is specified, the port will typically need to be set to 5061.

speaker_count Property

The number of records in the Speaker arrays.

Syntax

def get_speaker_count() -> int: ...

speaker_count = property(get_speaker_count, None)

Default Value

0

Remarks

This property controls the size of the following arrays:

The array indices start at 0 and end at speaker_count - 1.

This property is read-only.

speaker_channels Property

Number specifying whether the device supports mono (1) or stereo (2) output.

Syntax

def get_speaker_channels(speaker_index: int) -> int: ...

Default Value

0

Remarks

Number specifying whether the device supports mono (1) or stereo (2) output.

The speaker_index parameter specifies the index of the item in the array. The size of the array is controlled by the speaker_count property.

This property is read-only.

speaker_manufacturer_id Property

Manufacturer identifier for the device driver for the device.

Syntax

def get_speaker_manufacturer_id(speaker_index: int) -> int: ...

Default Value

0

Remarks

Manufacturer identifier for the device driver for the device.

The speaker_index parameter specifies the index of the item in the array. The size of the array is controlled by the speaker_count property.

This property is read-only.

speaker_name Property

Product name in a null-terminated string.

Syntax

def get_speaker_name(speaker_index: int) -> str: ...

Default Value

""

Remarks

Product name in a null-terminated string.

The speaker_index parameter specifies the index of the item in the array. The size of the array is controlled by the speaker_count property.

This property is read-only.

speaker_product_id Property

Product identifier for the device as assigned by Windows.

Syntax

def get_speaker_product_id(speaker_index: int) -> int: ...

Default Value

0

Remarks

Product identifier for the device as assigned by Windows.

The speaker_index parameter specifies the index of the item in the array. The size of the array is controlled by the speaker_count property.

This property is read-only.

speaker_support Property

Bitmask of optional functionalities supported by the device.

Syntax

def get_speaker_support(speaker_index: int) -> int: ...

Default Value

0

Remarks

Bitmask of optional functionalities supported by the device. This field can have one or more of the following values OR'd together:

BitmaskFlagDescription
0x0001WAVECAPS_PITCHSupports pitch control.
0x0002WAVECAPS_PLAYBACKRATESupports playback rate control.
0x0004WAVECAPS_VOLUMESupports volume control.
0x0008WAVECAPS_LRVOLUMESupports separate left and right volume control.
0x0010WAVECAPS_SYNCThe driver is synchronous and will block while playing a buffer.
0x0020WAVECAPS_SAMPLEACCURATE Returns sample-accurate position information.

The speaker_index parameter specifies the index of the item in the array. The size of the array is controlled by the speaker_count property.

This property is read-only.

speaker_supported_formats Property

Bitmask of standard formats that are supported.

Syntax

def get_speaker_supported_formats(speaker_index: int) -> int: ...

Default Value

0

Remarks

Bitmask of standard formats that are supported. This field can have one or more of the following values OR'd together:

BitmaskFormatDescription
0x00000001WAVE_FORMAT_1M0811.025 kHz, mono, 8-bit
0x00000002WAVE_FORMAT_1S0811.025 kHz, stereo, 8-bit
0x00000004WAVE_FORMAT_1M1611.025 kHz, mono, 16-bit
0x00000008WAVE_FORMAT_1S1611.025 kHz, stereo, 16-bit
0x00000010WAVE_FORMAT_2M0822.05 kHz, mono, 8-bit
0x00000020WAVE_FORMAT_2S0822.05 kHz, stereo, 8-bit
0x00000040WAVE_FORMAT_2M1622.05 kHz, mono, 16-bit
0x00000080WAVE_FORMAT_2S1622.05 kHz, stereo, 16-bit
0x00000100WAVE_FORMAT_4M0844.1 kHz, mono, 8-bit
0x00000200WAVE_FORMAT_4S0844.1 kHz, stereo, 8-bit
0x00000400WAVE_FORMAT_4M1644.1 kHz, mono, 16-bit
0x00000800WAVE_FORMAT_4S1644.1 kHz, stereo, 16-bit
0x00001000WAVE_FORMAT_48M0848 kHz, mono, 8-bit
0x00002000WAVE_FORMAT_48S0848 kHz, stereo, 8-bit
0x00004000WAVE_FORMAT_48M1648 kHz, mono, 16-bit
0x00008000WAVE_FORMAT_48S1648 kHz, stereo, 16-bit
0x00010000WAVE_FORMAT_96M0896 kHz, mono, 8-bit
0x00020000WAVE_FORMAT_96S0896 kHz, stereo, 8-bit
0x00040000WAVE_FORMAT_96M1696 kHz, mono, 16-bit
0x00080000WAVE_FORMAT_96S1696 kHz, stereo, 16-bit

The speaker_index parameter specifies the index of the item in the array. The size of the array is controlled by the speaker_count property.

This property is read-only.

ssl_accept_server_cert_effective_date Property

This is the date on which this certificate becomes valid.

Syntax

def get_ssl_accept_server_cert_effective_date() -> str: ...

ssl_accept_server_cert_effective_date = property(get_ssl_accept_server_cert_effective_date, None)

Default Value

""

Remarks

This is the date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

ssl_accept_server_cert_expiration_date Property

This is the date the certificate expires.

Syntax

def get_ssl_accept_server_cert_expiration_date() -> str: ...

ssl_accept_server_cert_expiration_date = property(get_ssl_accept_server_cert_expiration_date, None)

Default Value

""

Remarks

This is the date the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

ssl_accept_server_cert_extended_key_usage Property

This is a comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_accept_server_cert_extended_key_usage() -> str: ...

ssl_accept_server_cert_extended_key_usage = property(get_ssl_accept_server_cert_extended_key_usage, None)

Default Value

""

Remarks

This is a comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

ssl_accept_server_cert_fingerprint Property

This is the hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint() -> str: ...

ssl_accept_server_cert_fingerprint = property(get_ssl_accept_server_cert_fingerprint, None)

Default Value

""

Remarks

This is the hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

ssl_accept_server_cert_fingerprint_sha1 Property

This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint_sha1() -> str: ...

ssl_accept_server_cert_fingerprint_sha1 = property(get_ssl_accept_server_cert_fingerprint_sha1, None)

Default Value

""

Remarks

This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

ssl_accept_server_cert_fingerprint_sha256 Property

This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_ssl_accept_server_cert_fingerprint_sha256() -> str: ...

ssl_accept_server_cert_fingerprint_sha256 = property(get_ssl_accept_server_cert_fingerprint_sha256, None)

Default Value

""

Remarks

This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

ssl_accept_server_cert_issuer Property

This is the issuer of the certificate.

Syntax

def get_ssl_accept_server_cert_issuer() -> str: ...

ssl_accept_server_cert_issuer = property(get_ssl_accept_server_cert_issuer, None)

Default Value

""

Remarks

This is the issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

ssl_accept_server_cert_private_key Property

This is the private key of the certificate (if available).

Syntax

def get_ssl_accept_server_cert_private_key() -> str: ...

ssl_accept_server_cert_private_key = property(get_ssl_accept_server_cert_private_key, None)

Default Value

""

Remarks

This is the private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The ssl_accept_server_cert_private_key may be available but not exportable. In this case, ssl_accept_server_cert_private_key returns an empty string.

This property is read-only.

ssl_accept_server_cert_private_key_available Property

This property shows whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_accept_server_cert_private_key_available() -> bool: ...

ssl_accept_server_cert_private_key_available = property(get_ssl_accept_server_cert_private_key_available, None)

Default Value

FALSE

Remarks

This property shows whether a ssl_accept_server_cert_private_key is available for the selected certificate. If ssl_accept_server_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

ssl_accept_server_cert_private_key_container Property

This is the name of the PrivateKey container for the certificate (if available).

Syntax

def get_ssl_accept_server_cert_private_key_container() -> str: ...

ssl_accept_server_cert_private_key_container = property(get_ssl_accept_server_cert_private_key_container, None)

Default Value

""

Remarks

This is the name of the ssl_accept_server_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

ssl_accept_server_cert_public_key Property

This is the public key of the certificate.

Syntax

def get_ssl_accept_server_cert_public_key() -> str: ...

ssl_accept_server_cert_public_key = property(get_ssl_accept_server_cert_public_key, None)

Default Value

""

Remarks

This is the public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

ssl_accept_server_cert_public_key_algorithm Property

This property contains the textual description of the certificate's public key algorithm.

Syntax

def get_ssl_accept_server_cert_public_key_algorithm() -> str: ...

ssl_accept_server_cert_public_key_algorithm = property(get_ssl_accept_server_cert_public_key_algorithm, None)

Default Value

""

Remarks

This property contains the textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_accept_server_cert_public_key_length Property

This is the length of the certificate's public key (in bits).

Syntax

def get_ssl_accept_server_cert_public_key_length() -> int: ...

ssl_accept_server_cert_public_key_length = property(get_ssl_accept_server_cert_public_key_length, None)

Default Value

0

Remarks

This is the length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

ssl_accept_server_cert_serial_number Property

This is the serial number of the certificate encoded as a string.

Syntax

def get_ssl_accept_server_cert_serial_number() -> str: ...

ssl_accept_server_cert_serial_number = property(get_ssl_accept_server_cert_serial_number, None)

Default Value

""

Remarks

This is the serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

ssl_accept_server_cert_signature_algorithm Property

The property contains the text description of the certificate's signature algorithm.

Syntax

def get_ssl_accept_server_cert_signature_algorithm() -> str: ...

ssl_accept_server_cert_signature_algorithm = property(get_ssl_accept_server_cert_signature_algorithm, None)

Default Value

""

Remarks

The property contains the text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_accept_server_cert_store Property

This is the name of the certificate store for the client certificate.

Syntax

def get_ssl_accept_server_cert_store() -> bytes: ...
def set_ssl_accept_server_cert_store(value: bytes) -> None: ...

ssl_accept_server_cert_store = property(get_ssl_accept_server_cert_store, set_ssl_accept_server_cert_store)

Default Value

"MY"

Remarks

This is the name of the certificate store for the client certificate.

The ssl_accept_server_cert_store_type property denotes the type of the certificate store specified by ssl_accept_server_cert_store. If the store is password protected, specify the password in ssl_accept_server_cert_store_password.

ssl_accept_server_cert_store is used in conjunction with the ssl_accept_server_cert_subject property to specify client certificates. If ssl_accept_server_cert_store has a value, and ssl_accept_server_cert_subject or ssl_accept_server_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_accept_server_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

ssl_accept_server_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_accept_server_cert_store_password() -> str: ...
def set_ssl_accept_server_cert_store_password(value: str) -> None: ...

ssl_accept_server_cert_store_password = property(get_ssl_accept_server_cert_store_password, set_ssl_accept_server_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

ssl_accept_server_cert_store_type Property

This is the type of certificate store for this certificate.

Syntax

def get_ssl_accept_server_cert_store_type() -> int: ...
def set_ssl_accept_server_cert_store_type(value: int) -> None: ...

ssl_accept_server_cert_store_type = property(get_ssl_accept_server_cert_store_type, set_ssl_accept_server_cert_store_type)

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

0 (cstUser - default)For Windows, this specifies that the certificate store is a certificate store owned by the current user.

Note: This store type is not available in Java.

1 (cstMachine)For Windows, this specifies that the certificate store is a machine store.

Note: This store type is not available in Java.

2 (cstPFXFile)The certificate store is the name of a PFX (PKCS#12) file containing certificates.
3 (cstPFXBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format.
4 (cstJKSFile)The certificate store is the name of a Java Key Store (JKS) file containing certificates.

Note: This store type is only available in Java.

5 (cstJKSBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format.

Note: this store type is only available in Java.

6 (cstPEMKeyFile)The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)The certificate store is the name of a PKCS#7 file containing certificates.
12 (cstP7BBlob)The certificate store is a string (binary) representing a certificate store in PKCS#7 format.
13 (cstSSHPublicKeyFile)The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)The certificate store is a string that contains a JWK (JSON Web Key).
21 (cstBCFKSFile)The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store).

Note: This store type is only available in Java and .NET.

22 (cstBCFKSBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format.

Note: This store type is only available in Java and .NET.

23 (cstPKCS11)The certificate is present on a physical security key accessible via a PKCS#11 interface.

To use a security key, the necessary data must first be collected using the CERTMGR class. The list_store_certificates method may be called after setting cert_store_type to cstPKCS11, cert_store_password to the PIN, and cert_store to the full path of the PKCS#11 DLL. The certificate information returned in the on_cert_list event's CertEncoded parameter may be saved for later use.

When using a certificate, pass the previously saved security key information as the ssl_accept_server_cert_store and set ssl_accept_server_cert_store_password to the PIN.

Code Example. SSH Authentication with Security Key: certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);

99 (cstAuto)The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

ssl_accept_server_cert_subject_alt_names Property

This property contains comma-separated lists of alternative subject names for the certificate.

Syntax

def get_ssl_accept_server_cert_subject_alt_names() -> str: ...

ssl_accept_server_cert_subject_alt_names = property(get_ssl_accept_server_cert_subject_alt_names, None)

Default Value

""

Remarks

This property contains comma-separated lists of alternative subject names for the certificate.

This property is read-only.

ssl_accept_server_cert_thumbprint_md5 Property

This property contains the MD5 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_md5() -> str: ...

ssl_accept_server_cert_thumbprint_md5 = property(get_ssl_accept_server_cert_thumbprint_md5, None)

Default Value

""

Remarks

This property contains the MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_thumbprint_sha1 Property

This property contains the SHA-1 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_sha1() -> str: ...

ssl_accept_server_cert_thumbprint_sha1 = property(get_ssl_accept_server_cert_thumbprint_sha1, None)

Default Value

""

Remarks

This property contains the SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_thumbprint_sha256 Property

This property contains the SHA-256 hash of the certificate.

Syntax

def get_ssl_accept_server_cert_thumbprint_sha256() -> str: ...

ssl_accept_server_cert_thumbprint_sha256 = property(get_ssl_accept_server_cert_thumbprint_sha256, None)

Default Value

""

Remarks

This property contains the SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_accept_server_cert_usage Property

This property contains the text description of UsageFlags .

Syntax

def get_ssl_accept_server_cert_usage() -> str: ...

ssl_accept_server_cert_usage = property(get_ssl_accept_server_cert_usage, None)

Default Value

""

Remarks

This property contains the text description of ssl_accept_server_cert_usage_flags.

This value will be of one or more of the following strings and will be separated by commas:

  • Digital Signature
  • Non-Repudiation
  • Key Encipherment
  • Data Encipherment
  • Key Agreement
  • Certificate Signing
  • CRL Signing
  • Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

ssl_accept_server_cert_usage_flags Property

This property contains the flags that show intended use for the certificate.

Syntax

def get_ssl_accept_server_cert_usage_flags() -> int: ...

ssl_accept_server_cert_usage_flags = property(get_ssl_accept_server_cert_usage_flags, None)

Default Value

0

Remarks

This property contains the flags that show intended use for the certificate. The value of ssl_accept_server_cert_usage_flags is a combination of the following flags:

0x80Digital Signature
0x40Non-Repudiation
0x20Key Encipherment
0x10Data Encipherment
0x08Key Agreement
0x04Certificate Signing
0x02CRL Signing
0x01Encipher Only

Please see the ssl_accept_server_cert_usage property for a text representation of ssl_accept_server_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

ssl_accept_server_cert_version Property

This property contains the certificate's version number.

Syntax

def get_ssl_accept_server_cert_version() -> str: ...

ssl_accept_server_cert_version = property(get_ssl_accept_server_cert_version, None)

Default Value

""

Remarks

This property contains the certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

ssl_accept_server_cert_subject Property

This is the subject of the certificate used for client authentication.

Syntax

def get_ssl_accept_server_cert_subject() -> str: ...
def set_ssl_accept_server_cert_subject(value: str) -> None: ...

ssl_accept_server_cert_subject = property(get_ssl_accept_server_cert_subject, set_ssl_accept_server_cert_subject)

Default Value

""

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

FieldMeaning
CNCommon Name. This is commonly a hostname like www.server.com.
OOrganization
OUOrganizational Unit
LLocality
SState
CCountry
EEmail Address

If a field value contains a comma, it must be quoted.

ssl_accept_server_cert_encoded Property

This is the certificate (PEM/Base64 encoded).

Syntax

def get_ssl_accept_server_cert_encoded() -> bytes: ...
def set_ssl_accept_server_cert_encoded(value: bytes) -> None: ...

ssl_accept_server_cert_encoded = property(get_ssl_accept_server_cert_encoded, set_ssl_accept_server_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_accept_server_cert_store and ssl_accept_server_cert_subject properties also may be used to specify a certificate.

When ssl_accept_server_cert_encoded is set, a search is initiated in the current ssl_accept_server_cert_store for the private key of the certificate. If the key is found, ssl_accept_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_accept_server_cert_subject is set to an empty string.

ssl_cert_effective_date Property

This is the date on which this certificate becomes valid.

Syntax

def get_ssl_cert_effective_date() -> str: ...

ssl_cert_effective_date = property(get_ssl_cert_effective_date, None)

Default Value

""

Remarks

This is the date on which this certificate becomes valid. Before this date, it is not valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2000 15:00:00.

This property is read-only.

ssl_cert_expiration_date Property

This is the date the certificate expires.

Syntax

def get_ssl_cert_expiration_date() -> str: ...

ssl_cert_expiration_date = property(get_ssl_cert_expiration_date, None)

Default Value

""

Remarks

This is the date the certificate expires. After this date, the certificate will no longer be valid. The date is localized to the system's time zone. The following example illustrates the format of an encoded date:

23-Jan-2001 15:00:00.

This property is read-only.

ssl_cert_extended_key_usage Property

This is a comma-delimited list of extended key usage identifiers.

Syntax

def get_ssl_cert_extended_key_usage() -> str: ...

ssl_cert_extended_key_usage = property(get_ssl_cert_extended_key_usage, None)

Default Value

""

Remarks

This is a comma-delimited list of extended key usage identifiers. These are the same as ASN.1 object identifiers (OIDs).

This property is read-only.

ssl_cert_fingerprint Property

This is the hex-encoded, 16-byte MD5 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint() -> str: ...

ssl_cert_fingerprint = property(get_ssl_cert_fingerprint, None)

Default Value

""

Remarks

This is the hex-encoded, 16-byte MD5 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: bc:2a:72:af:fe:58:17:43:7a:5f:ba:5a:7c:90:f7:02

This property is read-only.

ssl_cert_fingerprint_sha1 Property

This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint_sha1() -> str: ...

ssl_cert_fingerprint_sha1 = property(get_ssl_cert_fingerprint_sha1, None)

Default Value

""

Remarks

This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 30:7b:fa:38:65:83:ff:da:b4:4e:07:3f:17:b8:a4:ed:80:be:ff:84

This property is read-only.

ssl_cert_fingerprint_sha256 Property

This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate.

Syntax

def get_ssl_cert_fingerprint_sha256() -> str: ...

ssl_cert_fingerprint_sha256 = property(get_ssl_cert_fingerprint_sha256, None)

Default Value

""

Remarks

This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate. This property is primarily used for keys which do not have a corresponding X.509 public certificate, such as PEM keys that only contain a private key. It is commonly used for SSH keys.

The following example illustrates the format: 6a:80:5c:33:a9:43:ea:b0:96:12:8a:64:96:30:ef:4a:8a:96:86:ce:f4:c7:be:10:24:8e:2b:60:9e:f3:59:53

This property is read-only.

ssl_cert_issuer Property

This is the issuer of the certificate.

Syntax

def get_ssl_cert_issuer() -> str: ...

ssl_cert_issuer = property(get_ssl_cert_issuer, None)

Default Value

""

Remarks

This is the issuer of the certificate. This property contains a string representation of the name of the issuing authority for the certificate.

This property is read-only.

ssl_cert_private_key Property

This is the private key of the certificate (if available).

Syntax

def get_ssl_cert_private_key() -> str: ...

ssl_cert_private_key = property(get_ssl_cert_private_key, None)

Default Value

""

Remarks

This is the private key of the certificate (if available). The key is provided as PEM/Base64-encoded data.

Note: The ssl_cert_private_key may be available but not exportable. In this case, ssl_cert_private_key returns an empty string.

This property is read-only.

ssl_cert_private_key_available Property

This property shows whether a PrivateKey is available for the selected certificate.

Syntax

def get_ssl_cert_private_key_available() -> bool: ...

ssl_cert_private_key_available = property(get_ssl_cert_private_key_available, None)

Default Value

FALSE

Remarks

This property shows whether a ssl_cert_private_key is available for the selected certificate. If ssl_cert_private_key_available is True, the certificate may be used for authentication purposes (e.g., server authentication).

This property is read-only.

ssl_cert_private_key_container Property

This is the name of the PrivateKey container for the certificate (if available).

Syntax

def get_ssl_cert_private_key_container() -> str: ...

ssl_cert_private_key_container = property(get_ssl_cert_private_key_container, None)

Default Value

""

Remarks

This is the name of the ssl_cert_private_key container for the certificate (if available). This functionality is available only on Windows platforms.

This property is read-only.

ssl_cert_public_key Property

This is the public key of the certificate.

Syntax

def get_ssl_cert_public_key() -> str: ...

ssl_cert_public_key = property(get_ssl_cert_public_key, None)

Default Value

""

Remarks

This is the public key of the certificate. The key is provided as PEM/Base64-encoded data.

This property is read-only.

ssl_cert_public_key_algorithm Property

This property contains the textual description of the certificate's public key algorithm.

Syntax

def get_ssl_cert_public_key_algorithm() -> str: ...

ssl_cert_public_key_algorithm = property(get_ssl_cert_public_key_algorithm, None)

Default Value

""

Remarks

This property contains the textual description of the certificate's public key algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_DH") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_cert_public_key_length Property

This is the length of the certificate's public key (in bits).

Syntax

def get_ssl_cert_public_key_length() -> int: ...

ssl_cert_public_key_length = property(get_ssl_cert_public_key_length, None)

Default Value

0

Remarks

This is the length of the certificate's public key (in bits). Common values are 512, 1024, and 2048.

This property is read-only.

ssl_cert_serial_number Property

This is the serial number of the certificate encoded as a string.

Syntax

def get_ssl_cert_serial_number() -> str: ...

ssl_cert_serial_number = property(get_ssl_cert_serial_number, None)

Default Value

""

Remarks

This is the serial number of the certificate encoded as a string. The number is encoded as a series of hexadecimal digits, with each pair representing a byte of the serial number.

This property is read-only.

ssl_cert_signature_algorithm Property

The property contains the text description of the certificate's signature algorithm.

Syntax

def get_ssl_cert_signature_algorithm() -> str: ...

ssl_cert_signature_algorithm = property(get_ssl_cert_signature_algorithm, None)

Default Value

""

Remarks

The property contains the text description of the certificate's signature algorithm. The property contains either the name of the algorithm (e.g., "RSA" or "RSA_MD5RSA") or an object identifier (OID) string representing the algorithm.

This property is read-only.

ssl_cert_store Property

This is the name of the certificate store for the client certificate.

Syntax

def get_ssl_cert_store() -> bytes: ...
def set_ssl_cert_store(value: bytes) -> None: ...

ssl_cert_store = property(get_ssl_cert_store, set_ssl_cert_store)

Default Value

"MY"

Remarks

This is the name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

MYA certificate store holding personal certificates with their associated private keys.
CACertifying authority certificates.
ROOTRoot certificates.

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

ssl_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_cert_store_password() -> str: ...
def set_ssl_cert_store_password(value: str) -> None: ...

ssl_cert_store_password = property(get_ssl_cert_store_password, set_ssl_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

ssl_cert_store_type Property

This is the type of certificate store for this certificate.

Syntax

def get_ssl_cert_store_type() -> int: ...
def set_ssl_cert_store_type(value: int) -> None: ...

ssl_cert_store_type = property(get_ssl_cert_store_type, set_ssl_cert_store_type)

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

0 (cstUser - default)For Windows, this specifies that the certificate store is a certificate store owned by the current user.

Note: This store type is not available in Java.

1 (cstMachine)For Windows, this specifies that the certificate store is a machine store.

Note: This store type is not available in Java.

2 (cstPFXFile)The certificate store is the name of a PFX (PKCS#12) file containing certificates.
3 (cstPFXBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in PFX (PKCS#12) format.
4 (cstJKSFile)The certificate store is the name of a Java Key Store (JKS) file containing certificates.

Note: This store type is only available in Java.

5 (cstJKSBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in Java Key Store (JKS) format.

Note: this store type is only available in Java.

6 (cstPEMKeyFile)The certificate store is the name of a PEM-encoded file that contains a private key and an optional certificate.
7 (cstPEMKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains a private key and an optional certificate.
8 (cstPublicKeyFile)The certificate store is the name of a file that contains a PEM- or DER-encoded public key certificate.
9 (cstPublicKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains a PEM- or DER-encoded public key certificate.
10 (cstSSHPublicKeyBlob)The certificate store is a string (binary or Base64-encoded) that contains an SSH-style public key.
11 (cstP7BFile)The certificate store is the name of a PKCS#7 file containing certificates.
12 (cstP7BBlob)The certificate store is a string (binary) representing a certificate store in PKCS#7 format.
13 (cstSSHPublicKeyFile)The certificate store is the name of a file that contains an SSH-style public key.
14 (cstPPKFile)The certificate store is the name of a file that contains a PPK (PuTTY Private Key).
15 (cstPPKBlob)The certificate store is a string (binary) that contains a PPK (PuTTY Private Key).
16 (cstXMLFile)The certificate store is the name of a file that contains a certificate in XML format.
17 (cstXMLBlob)The certificate store is a string that contains a certificate in XML format.
18 (cstJWKFile)The certificate store is the name of a file that contains a JWK (JSON Web Key).
19 (cstJWKBlob)The certificate store is a string that contains a JWK (JSON Web Key).
21 (cstBCFKSFile)The certificate store is the name of a file that contains a BCFKS (Bouncy Castle FIPS Key Store).

Note: This store type is only available in Java and .NET.

22 (cstBCFKSBlob)The certificate store is a string (binary or Base64-encoded) representing a certificate store in BCFKS (Bouncy Castle FIPS Key Store) format.

Note: This store type is only available in Java and .NET.

23 (cstPKCS11)The certificate is present on a physical security key accessible via a PKCS#11 interface.

To use a security key, the necessary data must first be collected using the CERTMGR class. The list_store_certificates method may be called after setting cert_store_type to cstPKCS11, cert_store_password to the PIN, and cert_store to the full path of the PKCS#11 DLL. The certificate information returned in the on_cert_list event's CertEncoded parameter may be saved for later use.

When using a certificate, pass the previously saved security key information as the ssl_cert_store and set ssl_cert_store_password to the PIN.

Code Example. SSH Authentication with Security Key: certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);

99 (cstAuto)The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

ssl_cert_subject_alt_names Property

This property contains comma-separated lists of alternative subject names for the certificate.

Syntax

def get_ssl_cert_subject_alt_names() -> str: ...

ssl_cert_subject_alt_names = property(get_ssl_cert_subject_alt_names, None)

Default Value

""

Remarks

This property contains comma-separated lists of alternative subject names for the certificate.

This property is read-only.

ssl_cert_thumbprint_md5 Property

This property contains the MD5 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_md5() -> str: ...

ssl_cert_thumbprint_md5 = property(get_ssl_cert_thumbprint_md5, None)

Default Value

""

Remarks

This property contains the MD5 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_thumbprint_sha1 Property

This property contains the SHA-1 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_sha1() -> str: ...

ssl_cert_thumbprint_sha1 = property(get_ssl_cert_thumbprint_sha1, None)

Default Value

""

Remarks

This property contains the SHA-1 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_thumbprint_sha256 Property

This property contains the SHA-256 hash of the certificate.

Syntax

def get_ssl_cert_thumbprint_sha256() -> str: ...

ssl_cert_thumbprint_sha256 = property(get_ssl_cert_thumbprint_sha256, None)

Default Value

""

Remarks

This property contains the SHA-256 hash of the certificate. It is primarily used for X.509 certificates. If the hash does not already exist, it is automatically computed.

This property is read-only.

ssl_cert_usage Property

This property contains the text description of UsageFlags .

Syntax

def get_ssl_cert_usage() -> str: ...

ssl_cert_usage = property(get_ssl_cert_usage, None)

Default Value

""

Remarks

This property contains the text description of ssl_cert_usage_flags.

This value will be of one or more of the following strings and will be separated by commas:

  • Digital Signature
  • Non-Repudiation
  • Key Encipherment
  • Data Encipherment
  • Key Agreement
  • Certificate Signing
  • CRL Signing
  • Encipher Only

If the provider is OpenSSL, the value is a comma-separated list of X.509 certificate extension names.

This property is read-only.

ssl_cert_usage_flags Property

This property contains the flags that show intended use for the certificate.

Syntax

def get_ssl_cert_usage_flags() -> int: ...

ssl_cert_usage_flags = property(get_ssl_cert_usage_flags, None)

Default Value

0

Remarks

This property contains the flags that show intended use for the certificate. The value of ssl_cert_usage_flags is a combination of the following flags:

0x80Digital Signature
0x40Non-Repudiation
0x20Key Encipherment
0x10Data Encipherment
0x08Key Agreement
0x04Certificate Signing
0x02CRL Signing
0x01Encipher Only

Please see the ssl_cert_usage property for a text representation of ssl_cert_usage_flags.

This functionality currently is not available when the provider is OpenSSL.

This property is read-only.

ssl_cert_version Property

This property contains the certificate's version number.

Syntax

def get_ssl_cert_version() -> str: ...

ssl_cert_version = property(get_ssl_cert_version, None)

Default Value

""

Remarks

This property contains the certificate's version number. The possible values are the strings "V1", "V2", and "V3".

This property is read-only.

ssl_cert_subject Property

This is the subject of the certificate used for client authentication.

Syntax

def get_ssl_cert_subject() -> str: ...
def set_ssl_cert_subject(value: str) -> None: ...

ssl_cert_subject = property(get_ssl_cert_subject, set_ssl_cert_subject)

Default Value

""

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

FieldMeaning
CNCommon Name. This is commonly a hostname like www.server.com.
OOrganization
OUOrganizational Unit
LLocality
SState
CCountry
EEmail Address

If a field value contains a comma, it must be quoted.

ssl_cert_encoded Property

This is the certificate (PEM/Base64 encoded).

Syntax

def get_ssl_cert_encoded() -> bytes: ...
def set_ssl_cert_encoded(value: bytes) -> None: ...

ssl_cert_encoded = property(get_ssl_cert_encoded, set_ssl_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

user Property

The username that is used when connecting to the SIP Server.

Syntax

def get_user() -> str: ...
def set_user(value: str) -> None: ...

user = property(get_user, set_user)

Default Value

""

Remarks

This property contains the username of the client attempting to connect to the SIP Server. This value will be used when activating the class via activate.

activate Method

Activates the class.

Syntax

def activate() -> None: ...

Remarks

This method is used to activate the class by registering to a SIP Server specified in the server and port properties. The username and password of the SIP Server must be provided via user and password properties for authorization, if applicable.

Example: ipphone.User = "MyUsername"; ipphone.Password = "MyPassword"; ipphone.Server = "HostNameOrIP"; ipphone.Port = 5060; ipphone.Activate(); Upon successful activation, the on_activated event will fire.

answer Method

Answers an incoming phone call.

Syntax

def answer(call_id: str) -> None: ...

Remarks

This method can be used to answer an incoming phone call, specified by CallId. This method can be used in conjunction with the on_incoming_call event, for example: ipphone.onIncomingCall += (sender, e) => { ipphone.Answer(e.CallId); }; If successful, on_call_ready will fire.

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

deactivate Method

Deactivates the class.

Syntax

def deactivate() -> None: ...

Remarks

This method is used to unregister the class from the SIP Server. If deactivation is successful, on_deactivated will fire.

decline Method

Declines an incoming phone call.

Syntax

def decline(call_id: str) -> None: ...

Remarks

This method can be used to decline an incoming phone call, specified by CallId. This method can be used in conjunction with the on_incoming_call event, for example: ipphone.onIncomingCall += (sender, e) => { ipphone.Decline(e.CallId); };

dial Method

Used to make a call.

Syntax

def dial(number: str, caller_number: str, wait: bool) -> str: ...

Remarks

This method is used to make a call to a particular user, given by Number. This method should only be called after the class has been successfully activated via activate. Initially, the on_outgoing_call event will fire after calling this method. on_dial_completed may fire when the dial process is complete. If successful, on_call_ready will fire after the outgoing call has been answered, declined, or ignored. If the call is declined or ignored, the class will be sent to voicemail, which can be ended with hangup.

The CallerNumber parameter specifies the optional caller ID. If given, the P-Asserted-Identity Header, specified in RFC 3325, will be sent in requests to the connected SIP Server. If left as an empty string, this header will not be sent.

The Wait parameter specifies whether the class should connect synchronously or asynchronously to the call. If True, the class will connect synchronously, and won't return until the call has been answered, declined, or ignored. If False, the class will connect asynchronously. The call's status can be checked through various events, such as on_outgoing_call, on_call_ready, and on_call_state_changed, or found in the call's State field. Exceptions throughout the call process will be reported in on_dial_completed, along with other call details.

NOTE: This method will return the CallId field of the call. This returned value may not always reflect the accurate CallId. In the case that Wait is true, this method will always return the accurate value. In the case that Wait is false, the returned value may not be accurate if the outgoing call is forwarded, or redirected, as the class must change this field. Both the updated and original CallId will be present within the on_dial_completed event. Any references to the original CallId must be updated accordingly. Please see on_dial_completed for more details. The below examples assume the outgoing call has been answered:

Example: "wait" is true string callId = ""; bool connected = false; ipphone.OnCallReady += (sender, e) => { connected = true; } try { callId = ipphone.Dial("123456789", "", true); } catch (IPWorksVoIPException e) { MessageBox.Show(e.Code + ": " + e.Message); } if (connected) { ipphone.PlayText(callId, "Hello"); } Example: "wait" is false bool connected = false; string callId = ""; ipphone.OnDialCompleted += (sender, e) => { if (e.ErrorCode != 0) { MessageBox.Show(e.ErrorCode + ": " + e.Description); // Handle error } if (e.OriginalCallId != e.CallId) { callId = e.CallId; // Update callId if redirect occurred } } ipphone.OnCallReady += (sender, e) => { connected = true; } string callId = ipphone.Dial("123456789", "", false); ... ... ... // Somewhere else... if (connected) { ipphone.PlayText(callId, "Hello"); }

do_events Method

This method processes events from the internal message queue.

Syntax

def do_events() -> None: ...

Remarks

When do_events is called, the class processes any available events. If no events are available, it waits for a preset period of time, and then returns.

forward Method

Used to forward an incoming call.

Syntax

def forward(call_id: str, number: str) -> None: ...

Remarks

This method can be used to implement call forwarding, allowing incoming calls, given by CallId to be forwarded to a particular user specified by Number. This method can be used in conjunction with the on_incoming_call event, for example: ipphone.onIncomingCall += (sender, e) => { ipphone.Forward(e.CallId, "123456789"); };

hangup Method

Used to hang up a specific call.

Syntax

def hangup(call_id: str) -> None: ...

Remarks

This method is used to terminate a specific call, specified by CallId. After the call has been successfully terminated, on_call_terminated will fire.

hangup_all Method

Used to hang up all calls.

Syntax

def hangup_all() -> None: ...

Remarks

This method is used to terminate all calls currently in the Call* properties. on_call_terminated will fire for each successfully terminated call.

hold Method

Places a call on hold.

Syntax

def hold(call_id: str) -> None: ...

Remarks

This method is used to place a call, specified by CallId, on hold.

join_conference Method

Adds a call to a conference call.

Syntax

def join_conference(call_id: str, conference_id: str) -> None: ...

Remarks

This method is used to add a call, specified by CallId, to a conference call.

The ConferenceId parameter specifies the unique Id of the conference call. If no conference ID exists, the class will start a new conference call with this ID.

leave_conference Method

Removes a call from a conference call.

Syntax

def leave_conference(call_id: str) -> None: ...

Remarks

This method is used to remove a call, specified by CallId, from a conference call. If the call is not a part of any conference call, an exception will be thrown.

list_conferences Method

Lists ongoing conference calls.

Syntax

def list_conferences() -> str: ...

Remarks

This method is used to list ongoing conferences any of the class's calls are currently a part of. Calling this will return a string with the following format:

ConferenceId_1: CallId_1, CallId_2

...

ConferenceId_n: CallId_3, CallId_4, CallId_5, ...

list_microphones Method

Lists all microphones detected on the system.

Syntax

def list_microphones() -> None: ...

Remarks

This method lists all microphones detected on the system. Calling this method will populate the Microphone* properties.

list_speakers Method

Lists all speakers detected on the system.

Syntax

def list_speakers() -> None: ...

Remarks

This method lists all speakers detected on the system. Calling this method will populate the Speaker* properties.

mute_microphone Method

Used to mute or unmute the microphone for a specified call.

Syntax

def mute_microphone(call_id: str, mute: bool) -> None: ...

Remarks

This method can be used to either mute or unmute the microphone for a specified call, given by CallId. When Mute is true, the microphone will be muted for the call. When false, the microphone will be unmuted.

mute_speaker Method

Used to mute or unmute the speaker for a specified call.

Syntax

def mute_speaker(call_id: str, mute: bool) -> None: ...

Remarks

This method can be used to either mute or unmute the speaker for a specified call, given by CallId. When Mute is true, the speaker will be muted for the call. When false, the speaker will be unmuted.

ping Method

Used to ping the server.

Syntax

def ping(timeout: int) -> None: ...

Remarks

This method is used to ping the SIP server by sending an OPTIONS request. If no server response is received by the class in Timeout seconds, ping will throw an error.

Note this method is only applicable when the component is active.

play_bytes Method

This method is used to play bytes to a call.

Syntax

def play_bytes(call_id: str, bytes_to_play: bytes, last_block: bool) -> None: ...

Remarks

This method is used to play bytes to a call, specified by the CallId parameter. These bytes are expected to have a sampling rate of 8 kHz and a bit depth of 16 bits per sample (PCM 8 kHz 16-bit format). The BytesToPlay parameter specifies the bytes that will be sent to the call. Internally, these bytes will be stored within a buffer. Once all bytes have played and the buffer is empty, the on_played event will fire.

The LastBlock parameter indicates whether the class will expect further uses of play_bytes. When true, this indicates that no additional bytes will be provided for this particular audio stream, and on_played will fire once after the bytes have been played. Until this parameter is specified as true, the class will be considered to be playing audio.

If LastBlock is false, this indicates that the class should expect more calls to play_bytes. Once all bytes have played and the buffer is empty, on_played will fire as expected, and will continue firing until the LastBlock parameter is set to true. Within on_played, the user can provide further bytes to play_bytes. Please see below for detailed examples on how to use this method with on_played.

Example: Playing audio from a stream MemoryStream playBytesStream = new MemoryStream(byteSource); phone.PlayBytes("callId", new byte[0], false); phone.OnPlayed += (o, e) => { if (e.Completed) { Console.WriteLine("Playing Bytes Completed"); } else { byte[] data = new byte[4096]; // Arbitrary length int dataLen = playBytesStream.Read(data, 0, data.Length); if (dataLen > 0) { byte[] newData = new byte[dataLen]; Array.Copy(data, newData, dataLen) // Normalize array phone.PlayBytes(e.CallId, newData, false); } else { phone.PlayBytes(e.CallId, null, true); } } }; Exmaple: Playing single audio block MemoryStream playBytesStream = new MemoryStream(byteSource); phone.PlayBytes("callId", playBytesStream.ToArray(), true); phone.OnPlayed += (o, e) => { Console.WriteLine("Done!"); // No further calls to PlayBytes are expected in this case }

play_file Method

Plays audio from a WAV file to a call.

Syntax

def play_file(call_id: str, wav_file: str) -> None: ...

Remarks

This method is used to play the audio from a WAV file to a particular call, given by CallId. Audio transmission will only occur when the call has connected and on_call_ready has fired. Only WAV files with a sampling rate of 8 kHz and a bit depth of 16 bits per sample are supported (PCM 8 kHz 16-bit format).

Note that this class can handle playing audio to concurrent calls. This method is non-blocking and will return immediately. The on_played event will fire when the audio for the specified call has finished playing. Consecutive uses of play_text or play_file can prevent prior audio transmissions from being completed. In the below example, on_played will only fire for the second call to play_text:

ipphone.PlayFile("callId", "C:\\hello.wav"); // Played will not fire for this ipphone.PlayText("callId", "This will interrupt the previous use if it has not finished playing.");

The WavFile parameter specifies the path to the WAV file.

play_text Method

Plays audio from a string to a call using Text-to-Speech.

Syntax

def play_text(call_id: str, text: str) -> None: ...

Remarks

This method is used to play the text from a string to a particular call, given by CallId, using Text-to-Speech. Audio transmission will only occur when the call has connected and on_call_ready has fired.

Note that this class can handle playing audio to concurrent calls. This method is non-blocking and will return immediately. The on_played event will fire when the audio for the specified call has finished playing. Consecutive uses of play_text and play_file can prevent prior audio transmissions from completing. In the below example, on_played will only fire for the second call to play_text:

ipphone.PlayFile("callId", "C:\\hello.wav"); // Played will not fire for this ipphone.PlayText("callId", "This will interrupt the previous use if it has not finished playing.");

The Text parameter must be a string representation of the text to be transmitted.

reset Method

This method will reset the class.

Syntax

def reset() -> None: ...

Remarks

This method will reset the class's properties to their default values.

set_microphone Method

Sets the microphone used by the class.

Syntax

def set_microphone(microphone: str) -> None: ...

Remarks

This method is used to set the Microphone that will be used by the class.

The Microphone parameter specifies the name of the microphone to be set. To get the available microphones on the system, call list_microphones. Then, set the microphone with a name specified in the Microphone* properties.

Example ipphone.ListMicrophones(); ipphone.SetMicrophone(ipphone.Microphones[0].Name);

set_speaker Method

Sets the speaker used by the class.

Syntax

def set_speaker(speaker: str) -> None: ...

Remarks

This method is used to set the speaker that will be used by the class.

The Speaker parameter specifies the name of the speaker to be set. To get the available speakers on the system, call list_speakers. Then, set the speaker with a name specified in the Speaker* properties.

Example ipphone.ListSpeakers(); ipphone.SetSpeaker(ipphone.Speakers[0].Name);

start_recording Method

Used to start recording the audio of a call.

Syntax

def start_recording(call_id: str, filename: str) -> None: ...

Remarks

This method is used to start recording the incoming and outgoing audio of a call, specified by CallId. If you wish to record the audio to file, you may specify the Filename parameter. Note that when this parameter is specified, you must record to a WAV file.

You may also leave the Filename parameter blank if you want more direct control over the recorded data. This will cause the on_record event to fire containing the call's audio data once the recording is finished.

In both scenarios, you can stop recording the call's audio via stop_recording. By default, the recording will end if the call is terminated. Note the recorded audio will have a sampling rate of 8 kHz and a bit depth of 16 bits per sample (PCM 8 kHz 16-bit format).

Example: Using the 'Record' event MemoryStream recordStream = new MemoryStream(); phone.StartRecording("callId", ""); phone.OnRecord += (o, e) => { recordStream.Write(e.RecordedDataB, 0, e.RecordedDataB.Length); File.WriteAllBytes(recordFile, recordStream.ToArray()); };

stop_playing Method

Stops audio from playing to a call.

Syntax

def stop_playing(call_id: str) -> None: ...

Remarks

This method is used to stop the audio playing to a call, given by CallId. Note that this will not stop audio from transmitting with an external device set using set_microphone, however, will stop audio transmitting from usage of play_text, play_file, and play_bytes.

Note that on_played will not fire when this method is used.

stop_recording Method

Stops recording the audio of a call.

Syntax

def stop_recording(call_id: str) -> None: ...

Remarks

This method is used to stop recording the audio of a call, given by CallId. The class will automatically stop recording upon call termination.

transfer Method

Transfers a call.

Syntax

def transfer(call_id: str, number: str) -> None: ...

Remarks

This method is used to transfer a call, specified by CallId, to the phone number given by Number. The class supports the following types of transfers:

Basic Transfers

Basic transfers are very simple to perform. First, the user must establish a call with the number they will be transferring (transferee). After the call is established, the user can transfer the call to the appropriate number (transfer target). The call will then be removed. For example:

string callId = ipphone1.Dial("123456789", "", true); // Establish call with transferee, hold if needed //ipphone1.Hold(callId); ipphone1.Transfer(callId, "number");

Attended Transfers

Typically, attended transfers are used to manually check if the Number (or transfer target) is available for a call, provide extra information about the call, etc., before transferring. In addition to establishing a call with the transferee, the class must also establish a call with the transfer target. Once both of these calls are active, you may perform an attended transfer by calling transfer at any moment. Afterwards, a session between these calls will be established and they will be removed. Note that transfer must be used with the CallId of the call you wish to transfer (transferee) and the Number of the call you wish to transfer to (transfer target). For example:

string callId1 = ipphone1.Dial("123456789", "", true); // Establish call with Transferee, hold if needed //ipphone1.Hold(callId1); string callId2 = ipphone1.Dial("number", "", true); // Establish call with Transfer Target, hold if needed //ipphone1.Hold(callId2); ipphone1.Transfer(callId1, "number");

Note in these examples, hold can be used to place a call on hold before a transfer. This is optional.

type_digit Method

Used to type a digit.

Syntax

def type_digit(call_id: str, digit: str) -> None: ...

Remarks

This method can be used to type a digit, mimicking the functionality of a phone's keypad.

The CallId parameter specifies the call that will receive the virtual keypad input.

The Digit parameter specifies the digit that will be typed. Valid inputs include: 0-9, *, #

unhold Method

Takes a call off hold.

Syntax

def unhold(call_id: str) -> None: ...

Remarks

This method is used to take a call, specified by CallId, off hold.

on_activated Event

This event is fired immediately after the class is activated.

Syntax

class IPPhoneActivatedEventParams(object):
# In class IPPhone:
@property
def on_activated() -> Callable[[IPPhoneActivatedEventParams], None]: ...
@on_activated.setter
def on_activated(event_hook: Callable[[IPPhoneActivatedEventParams], None]) -> None: ...

Remarks

The on_activated event will fire after the class has successfully registered with the SIP Server via activate.

on_call_ready Event

This event is fired after a call has been answered, declined, or ignored.

Syntax

class IPPhoneCallReadyEventParams(object):
  @property
  def call_id() -> str: ...

# In class IPPhone:
@property
def on_call_ready() -> Callable[[IPPhoneCallReadyEventParams], None]: ...
@on_call_ready.setter
def on_call_ready(event_hook: Callable[[IPPhoneCallReadyEventParams], None]) -> None: ...

Remarks

For all calls, this event will fire when audio can be transmitted and received. For incoming calls, it will fire after the call has been answered.

For outgoing calls, this event will fire after the call has either been answered, declined, or ignored. In the case that the call is declined or ignored, it will fire and the class will be sent to voicemail. hangup can be used to end the call in all scenarios.

Note that this event will fire after on_outgoing_call and on_dial_completed, assuming dial was successful.

The CallId parameter is the unique Id of the call.

on_call_state_changed Event

This event is fired after a call's state has changed.

Syntax

class IPPhoneCallStateChangedEventParams(object):
  @property
  def call_id() -> str: ...

  @property
  def state() -> int: ...

# In class IPPhone:
@property
def on_call_state_changed() -> Callable[[IPPhoneCallStateChangedEventParams], None]: ...
@on_call_state_changed.setter
def on_call_state_changed(event_hook: Callable[[IPPhoneCallStateChangedEventParams], None]) -> None: ...

Remarks

The on_call_state_changed event will fire each time the state of a call has changed.

The CallId parameter is the unique Id of the call.

The State parameter denotes the state the call has changed to. The following values are applicable:

csInactive (0)The call is inactive (default setting).
csConnecting (1)The call is establishing a connection to the callee.
csAutConnecting (2)The call is establishing a connection to the callee with authorization credentials.
csRinging (3)The call is ringing.
csActive (4)The call is active.
csActiveInConference (5)The call is active and in a conference.
csDisconnecting (6)The call is disconnecting with the callee.
csAutDisconnecting (7)The call is disconnecting with the callee with authorization credentials.
csHolding (8)The call is currently being placed on hold, but the hold operation has not finished.
csOnHold (9)The call is currently on hold.
csUnholding (10)The call is currently being unheld, but the unhold operation has not finished.
csTransferring (11)The call is currently being transferred.
csAutTransferring (12)The call is currently being transferred with authorization credentials.

on_call_terminated Event

This event is fired after a call has been terminated.

Syntax

class IPPhoneCallTerminatedEventParams(object):
  @property
  def call_id() -> str: ...

# In class IPPhone:
@property
def on_call_terminated() -> Callable[[IPPhoneCallTerminatedEventParams], None]: ...
@on_call_terminated.setter
def on_call_terminated(event_hook: Callable[[IPPhoneCallTerminatedEventParams], None]) -> None: ...

Remarks

The on_call_terminated event will fire after a call has been terminated by either end of the call.

The CallId parameter is the unique Id of the call.

on_deactivated Event

This event is fired immediately after the class is deactivated.

Syntax

class IPPhoneDeactivatedEventParams(object):
# In class IPPhone:
@property
def on_deactivated() -> Callable[[IPPhoneDeactivatedEventParams], None]: ...
@on_deactivated.setter
def on_deactivated(event_hook: Callable[[IPPhoneDeactivatedEventParams], None]) -> None: ...

Remarks

The on_deactivated event will fire after the class has unregistered from the SIP Server via deactivate.

on_dial_completed Event

This event is fired after the dial process has finished.

Syntax

class IPPhoneDialCompletedEventParams(object):
  @property
  def original_call_id() -> str: ...

  @property
  def call_id() -> str: ...

  @property
  def caller() -> str: ...

  @property
  def callee() -> str: ...

  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class IPPhone:
@property
def on_dial_completed() -> Callable[[IPPhoneDialCompletedEventParams], None]: ...
@on_dial_completed.setter
def on_dial_completed(event_hook: Callable[[IPPhoneDialCompletedEventParams], None]) -> None: ...

Remarks

This event will fire when the dial process, initiated by calling dial, has completed. Note that this event will not fire if an exception occurs when the "wait" parameter of dial is true. In this case, the class will throw an exception. However, it will fire if "wait" is true and no exception occurs, indicating dial was successful.

The OriginalCallId parameter is the value returned by dial.

The value of the CallId parameter depends on the redirection status of the call. There are two scenarios:

  1. The outgoing call has not been redirected. In this case, CallId is equal to OriginalCallId, and the value returned by dial is correct.
  2. The outgoing call has been redirected any number of times. In this case, the OriginalCallId is no longer applicable, and the CallId parameter is the new unique identifier for this call. Any reference to the past value, OriginalCallId, should be updated accordingly to reflect the change due to redirection. This would also include references to the original value returned by dial.
The Caller parameter specifies the user that initially made the call. The Callee parameter specifies the final recipient of the call.

Errors during the dial process are reported via the ErrorCode and Description parameters. An error code of 0 and description of "Dialed Successfully" indicate dial has completed with no issues. A list of error codes can be found in the Error Codes section. In the case of a non-zero ErrorCode, the Description parameter will contain the error message (and SIP response code, if applicable), for example, "Dial Timeout" or "486: Busy Here".

on_digit Event

This event fires every time a digit is pressed using the keypad.

Syntax

class IPPhoneDigitEventParams(object):
  @property
  def call_id() -> str: ...

  @property
  def digit() -> str: ...

# In class IPPhone:
@property
def on_digit() -> Callable[[IPPhoneDigitEventParams], None]: ...
@on_digit.setter
def on_digit(event_hook: Callable[[IPPhoneDigitEventParams], None]) -> None: ...

Remarks

The on_digit event will fire after every detected keypad input from a call.

The detected input will be present in the Digit parameter. Note, this event will not fire after the class's inputs via type_digit. Detectable inputs include: 0-9, *, #

The CallId parameter is the unique Id of the call.

on_error Event

Fired when information is available about errors during data delivery.

Syntax

class IPPhoneErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class IPPhone:
@property
def on_error() -> Callable[[IPPhoneErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[IPPhoneErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing. Normally the class fails with an error.

The ErrorCode parameter contains an error code, and the Description parameter contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_incoming_call Event

This event is fired when an incoming call is received.

Syntax

class IPPhoneIncomingCallEventParams(object):
  @property
  def call_id() -> str: ...

  @property
  def remote_user() -> str: ...

  @property
  def request_uri() -> str: ...

  @property
  def to_uri() -> str: ...

# In class IPPhone:
@property
def on_incoming_call() -> Callable[[IPPhoneIncomingCallEventParams], None]: ...
@on_incoming_call.setter
def on_incoming_call(event_hook: Callable[[IPPhoneIncomingCallEventParams], None]) -> None: ...

Remarks

The on_incoming_call event will fire when an incoming call is received.

The CallId parameter specifies the unique Id of the call, and can be used to answer or decline the call.

The RemoteUser parameter indicates the username or telephone number of the remote user associated with the call.

The RequestURI parameter specifies the contact information of the current recipient associated with the call. This parameter is typically of the format sip:user@domain:port.

The ToURI parameter specifies the URI present in the To header. This URI contains the contact information information of the original recipient associated with the call. This parameter is typically of the format sip:user@domain.

Note the user and domain within the ToURI indicate the original recipient of the call as initially specified by the caller. This value may not reflect the current (or final) recipient of the call as denoted by the RequestURI.

on_log Event

This event is fired once for each log message.

Syntax

class IPPhoneLogEventParams(object):
  @property
  def log_level() -> int: ...

  @property
  def message() -> str: ...

  @property
  def log_type() -> str: ...

# In class IPPhone:
@property
def on_log() -> Callable[[IPPhoneLogEventParams], None]: ...
@on_log.setter
def on_log(event_hook: Callable[[IPPhoneLogEventParams], None]) -> None: ...

Remarks

This event fires once for each log message generated by the class. The verbosity is controlled by the LogLevel configuration.

LogLevel indicates the detail level of the message. Possible values are:

0 (None) No messages are logged.
1 (Info - Default) Informational events such as a call's status are logged.
2 (Verbose) Detailed data such as SIP/SDP packet information is logged.
3 (Debug) Debug data including all relevant sent and received audio bytes are logged.
Note: When LogLevel is set to 3 (Debug), we strongly advise against performing long-running operations inside of this event due to large amounts of sent and received audio bytes. For example, continuously updating an interface displaying the Log data will cause major performance issues in an application. It is recommended to set LogLevel to 3 only when writing Log data to a stream or file. There will be no performance issues in this case.

Message is the log message.

LogType identifies the type of log entry. Possible values are as follows:

  • Info
  • Packet
  • RTP

on_outgoing_call Event

This event is fired when an outgoing call has been made.

Syntax

class IPPhoneOutgoingCallEventParams(object):
  @property
  def call_id() -> str: ...

  @property
  def remote_user() -> str: ...

# In class IPPhone:
@property
def on_outgoing_call() -> Callable[[IPPhoneOutgoingCallEventParams], None]: ...
@on_outgoing_call.setter
def on_outgoing_call(event_hook: Callable[[IPPhoneOutgoingCallEventParams], None]) -> None: ...

Remarks

The on_outgoing_call event is fired when an outgoing call has been made using dial. This event signifies the start of the invite process.

The CallId parameter is the unique Id of the call.

The RemoteUser parameter indicates the username or telephone number of the remote user associated with the call.

on_played Event

This event is fired after the class finishes playing available audio.

Syntax

class IPPhonePlayedEventParams(object):
  @property
  def call_id() -> str: ...

  @property
  def completed() -> bool: ...

# In class IPPhone:
@property
def on_played() -> Callable[[IPPhonePlayedEventParams], None]: ...
@on_played.setter
def on_played(event_hook: Callable[[IPPhonePlayedEventParams], None]) -> None: ...

Remarks

The on_played event will fire after the class finishes playing available audio to a call. When using play_text or play_file, Completed will always be true. However, this will not always be the case when using play_bytes.

When playing audio via play_bytes, this event will fire when the internal byte queue is empty. In the event that the internal byte queue is empty, and the class is still expecting calls to play_bytes (i.e., lastBlock is false), this event will continue to fire with the Completed parameter as false. In this case, additional bytes are expected to be provided. Completed will be true once all bytes have been played and the class is no longer expecting calls to play_bytes (i.e., lastBlock is true). Please see the method description for more details.

The CallId parameter is the unique Id of the call.

on_record Event

This event is fired when recorded audio data is available.

Syntax

class IPPhoneRecordEventParams(object):
  @property
  def call_id() -> str: ...

  @property
  def recorded_data() -> bytes: ...

# In class IPPhone:
@property
def on_record() -> Callable[[IPPhoneRecordEventParams], None]: ...
@on_record.setter
def on_record(event_hook: Callable[[IPPhoneRecordEventParams], None]) -> None: ...

Remarks

This event is fired when a call's recorded data is available. This data is made available when either stop_recording is called or the call is terminated. Note that for this event to fire, start_recording must be specified with no filename parameter.

The recorded data will be available in the RecordedData and RecordedDataB parameters, and will have a sampling rate of 8 kHz and a bit depth of 16 bits per sample (PCM 8 kHz 16-bit format).

The CallId parameter is the unique Id of the call.

on_silence Event

This event is fired when the class detects silence from incoming audio streams.

Syntax

class IPPhoneSilenceEventParams(object):
  @property
  def call_id() -> str: ...

# In class IPPhone:
@property
def on_silence() -> Callable[[IPPhoneSilenceEventParams], None]: ...
@on_silence.setter
def on_silence(event_hook: Callable[[IPPhoneSilenceEventParams], None]) -> None: ...

Remarks

The on_silence event will fire every second the class detects silence from a call's incoming audio stream. Note that this event can fire while an outgoing call is ringing.

The CallId parameter is the unique Id of the call.

on_ssl_server_authentication Event

Fired after the server presents its certificate to the client.

Syntax

class IPPhoneSSLServerAuthenticationEventParams(object):
  @property
  def cert_encoded() -> bytes: ...

  @property
  def cert_subject() -> str: ...

  @property
  def cert_issuer() -> str: ...

  @property
  def status() -> str: ...

  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...

# In class IPPhone:
@property
def on_ssl_server_authentication() -> Callable[[IPPhoneSSLServerAuthenticationEventParams], None]: ...
@on_ssl_server_authentication.setter
def on_ssl_server_authentication(event_hook: Callable[[IPPhoneSSLServerAuthenticationEventParams], None]) -> None: ...

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

on_ssl_status Event

Fired when secure connection progress messages are available.

Syntax

class IPPhoneSSLStatusEventParams(object):
  @property
  def message() -> str: ...

# In class IPPhone:
@property
def on_ssl_status() -> Callable[[IPPhoneSSLStatusEventParams], None]: ...
@on_ssl_status.setter
def on_ssl_status(event_hook: Callable[[IPPhoneSSLStatusEventParams], None]) -> None: ...

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

IPPhone Config Settings

The class accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

IPPhone Config Settings

AudioDirection:   Indicates the direction of available recorded audio when dynamic recording is enabled.

This configuration is used to indicate the direction of available recorded audio when dynamic recording is enabled via EnableDynamicRecording. When EnableDynamicRecording is enabled and start_recording has been called with no filename parameter, this configuration can be queried within on_record to determine whether the recorded audio data is incoming or outgoing audio. A value of "0" indicates the audio is outgoing. A value of "1" indicates the audio is incoming. Aside from the above case, this configuration should not be interpreted elsewhere.

AuthUser:   Specifies the username to be used during client authentication.

This configuration is used to specify the username to be used when authenticating a SIP client, for example, when registering or initiating a call. When specified, this value will replace the user property within the Authorization and Proxy-Authorization headers sent in the mentioned requests.

By default, this value is empty, and the user property will be used within the mentioned headers.

Codecs:   Comma-separated list of codecs the class can use.

This configuration contains a comma-separated list of codecs, represented as integers, that the class can use to compress call data. By default, this value is:

8,0,3

The following integers correspond to these supported codecs:

0PCMU (G711MU)
3GSM
8PCMA (G711A)

DeclineStatus:   Specifies the status to send when declining an incoming call.

This configuration is used to specify the status to send when declining an incoming call. By default, this configuration will be empty and the class will send 486 Busy Here when calling decline. Valid responses when declining a call can be found in RFC 3261 Section 21. Note this configuration must be set to the response code and description, for example:

Component.Config("DeclineStatus=600 Busy Everywhere")

DialTimeout:   Specifies the amount of time to wait for a response when making a call.

This configuration is used to specify the amount of time (in seconds) the class will wait for the outgoing call to be answered, declined, or ignored when using dial. Note this value will be 60 by default.

When using dial with the Wait parameter as false, the timeout will be reported within on_dial_completed.

DialToneFile:   Specifies the location of the WAV file to play when making a call.

This configuration is used to specify the WAV file to play when making a call. Once the call is answered or terminated, the file will stop playing. Note this file will play when making a call, but only in the case that early media has not been established by the server. In the event the server has established early media, the server's dial tone will be heard instead. Only WAV files with a sampling rate of 8 kHz and a bit depth of 16 bits per sample are supported (PCM 8 kHz 16-bit format).

DisableRegistration:   Can be used to disable SIP registration.

This configuration can be used to disable SIP registration. By default, this configuration is set to False and registration is enabled. When set to True and activate is called, the class will attempt to establish a connection with the server using the underlying transport protocol specified by sip_transport_protocol. After a successful connection, the class will be considered active until the connection is removed by either end.

Note: It is recommended to enable this configuration only if sip_transport_protocol is set to TCP or TLS.

Domain:   Can be used to set the address of the SIP domain.

This configuration is used to specify the domain name the component will use in SIP requests, if needed. By default this value will be empty.

DtmfMethod:   The method used for delivering the signals/tones sent when typing a digit.

This configuration is used to describe the method being used to transmit the signals/tones when calling type_digit. Possible values of supported methods are:

1 Inband (Default)
2 RFC 2833
3 Info (SIP Info)
EnableDynamicRecording:   Specifies whether dynamic recording is enabled when recording a call.

This configuration is used to specify whether dynamic recording is enabled when recording a call. By default, this configuration is disabled (false). When enabled (true), and start_recording was called with no filename parameter specified, on_record will fire when incoming audio is sent and received. Within on_record, the data will either be incoming or outgoing audio. This can be determined by querying the AudioDirection configuration.

LogEncodedAudioData:   Whether the class will log encoded audio data.

This configuration controls whether the class will log encoded audio data when LogLevel is set to 3 (Debug). By default, this configuration is false, and the class will only log raw audio data.

LogLevel:   The level of detail that is logged.

This configuration controls the level of detail that is logged through the on_log event. Possible values are:

0 (None) No messages are logged.
1 (Info - Default) Informational events such as a call's status are logged.
2 (Verbose) Detailed data such as SIP/SDP packet information is logged.
3 (Debug) Debug data including all relevant sent and received audio bytes are logged.
Note: When LogLevel is set to 3 (Debug), we strongly advise against performing long-running operations inside of this event due to large amounts of sent and received audio bytes. For example, continuously updating an interface displaying the Log data will cause major performance issues in an application. It is recommended to set LogLevel to 3 only when writing Log data to a stream or file. There will be no performance issues in this case.

LogRTPPackets:   Whether the class will log RTP packets.

This configuration controls whether the class will log received RTP packets when LogLevel is set to 3 (Debug). By default, this configuration is false, and the class will only log audio data.

RecordType:   The type of recording the class will use.

This configuration sets the recording type the class will use when calling start_recording. Possible values are 0 (Mono) and 1 (Stereo - Default).

RedirectLimit:   The maximum number of redirects an outgoing call can experience.

This configuration limits the number of redirects, also known as forwards or diversions, an outgoing call can experience. If the number of redirects exceeds this value, an exception will be thrown. Note this value is 0 by default.

RefreshInterval:   Used to manually specify the interval between subsequent registration messages after successful activation.

By default, this configuration is set to 0, and RegistrationInterval will denote the interval at which the current registration is refreshed. When set to a positive value, this configuration denotes the interval at which the current registration is refreshed, in seconds.

If the client wishes to refresh the registration prior to the expected expiration, this configuration should be set appropriately. To do so, after successful activation, the RegistrationInterval should be queried to determine the existing lifetime. This configuration should then be set to a value less than or equal to the queried RegistrationInterval. For example:

component.Activate(); int lifetime = component.Config("RegistrationInterval"); // Refresh the registration halfway through it's lifetime. component.Config("RefreshInterval=" + (lifetime / 2));

RegistrationInterval:   Specifies the lifetime of the current registration.

Prior to activation, this configuration can be used to specify the clients desired lifetime for the current registration, in seconds. Note that this is merely a suggestion to the server, as the server determines the final lifetime of the registration. By default, this configuration is set to 60.

After calling activate, this configuration will be equal to the lifetime of the registration as decided by the server. By default, the class will automatically attempt to refresh the registration every RegistrationInterval seconds. This value can be overridden by setting the RefreshInterval configuration to a positive value.

RingtoneFile:   Specifies location of a WAV file to play when receiving an incoming call.

This configuration is used to specify a WAV file to play when receiving an incoming call. The ringtone will play until all incoming calls are answered declined, or ignored. Only WAV files with a sampling rate of 8 kHz and a bit depth of 16 bits per sample are supported (PCM 8 kHz 16-bit format).

SilenceInterval:   Specifies the interval the class uses to detect periods of silence.

This configuration is used to specify the interval (in milliseconds) that the class uses to detect silence from a call's incoming audio stream. This will also directly control the rate that on_silence will fire in the case silence is detected. Note this value is 1000 by default.

STUNPort:   The port of the STUN server.

This configuration sets the port of the corresponding STUNServer. This value will be 3478 by default.

STUNServer:   The address of the STUN Server.

This configuration sets the address of the STUN Server the class will use to communicate with the SIP Server.

UnregisterOnActivate:   Specifies whether the class will unregister from the SIP Server before registration.

When calling activate, this configuration will specify whether the component will unregister with the SIP Server before the initial registration. If False (default), the component will not attempt to unregister first, and will only perform registration.

VoiceIndex:   The voice that will be used when playing text.

This configuration sets the voice that will be used when calling play_text. The available voice tokens are listed in the registry under HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Speech\\Voices\\Tokens. Note this value will be 0 by default.

VoiceRate:   The speaking rate of the voice when playing text.

This configuration specifies the speaking rate of the voice when calling play_text. Supported values range from -10 (slowest) to 10 (fastest). Note this value will be 0 by default.

UDP Config Settings

CaptureIPPacketInfo:   Used to capture the packet information.

If this is set to True, the component will capture the IP packet information.

The default value for this setting is False.

Note: This configuration setting is available only in Windows.

DelayHostResolution:   Whether the hostname is resolved when RemoteHost is set.

This configuration setting specifies whether a hostname is resolved immediately when remote_host is set. If True the class will resolve the hostname and the IP address will be present in the remote_host property. If False, the hostname is not resolved until needed by the component when a method to connect or send data is called. If desired, resolve_remote_host may be called to manually resolve the value in remote_host at any time.

The default value is False.

DestinationAddress:   Used to get the destination address from the packet information.

If CaptureIPPacketInfo is set to True, then this will be populated with the packet's destination address when a packet is received. This information will be accessible in the DataIn event.

Note: This configuration setting is available only in Windows.

DontFragment:   Used to set the Don't Fragment flag of outgoing packets.

When set to True, packets sent by the class will have the Don't Fragment flag set. The default value is False.

LocalHost:   The name of the local host through which connections are initiated or accepted.

The local_host setting contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface), setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

If the class is connected, the local_host setting shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

LocalPort:   The port in the local host where the class binds.

This configuration setting must be set before a connection is attempted. It instructs the class to bind to a specific port (or communication endpoint) in the local machine.

Setting this to 0 (default) enables the system to choose a port at random. The chosen port will be shown by local_port after the connection is established.

local_port cannot be changed once a connection is made. Any attempt to set this when a connection is active will generate an error.

This configuration setting is useful when trying to connect to services that require a trusted port on the client side. An example is the remote shell (rsh) service in UNIX systems.

MaxPacketSize:   The maximum length of the packets that can be received.

This configuration setting specifies the maximum size of the datagrams that the class will accept without truncation.

QOSDSCPValue:   Used to specify an arbitrary QOS/DSCP setting (optional).

UseConnection must be True to use this configuration setting. This option allows you to specify an arbitrary DSCP value between 0 and 63. The default is 0. When set to the default value, the component will not set a DSCP value.

Note: This configuration setting uses the qWAVE API and is available only on Windows 7, Windows Server 2008 R2, and later.

QOSTrafficType:   Used to specify QOS/DSCP settings (optional).

UseConnection must be True to use this setting. You may specify either the text or integer values: BestEffort (0), Background (1), ExcellentEffort (2), AudioVideo (3), Voice (4), and Control (5).

Note: This configuration setting uses the qWAVE API and is available only on Windows Vista and Windows Server 2008 or above.

Note: QOSTrafficType must be set before setting active to True.

ShareLocalPort:   If set to True, allows more than one instance of the class to be active on the same local port.

This option must be set before the class is activated through the active property or it will have no effect.

The default value for this setting is False.

SourceIPAddress:   Used to set the source IP address used when sending a packet.

This configuration setting can be used to override the source IP address when sending a packet.

Note: This configuration setting is available only in Windows and requires that the winpcap library be installed (or npcap with winpcap compatibility).

SourceMacAddress:   Used to set the source MAC address used when sending a packet.

This configuration setting can be used to override the source MAC address when sending a packet.

Note: This configuration setting is available only in Windows and requires that the winpcap library be installed (or npcap with winpcap compatibility).

UseConnection:   Determines whether to use a connected socket.

UseConnection specifies whether or not the class should use a connected socket. The connection is defined as an association in between the local address/port and the remote address/port. As such, this is not a connection in the traditional Transmission Control Protocol (TCP) sense. It means only that the class will send and receive data to and from the specified destination.

The default value for this setting is False.

UseIPv6:   Whether or not to use IPv6.

By default, the component expects an IPv4 address for local and remote host properties, and it will create an IPv4 socket. To use IPv6 instead, set this to True.

Socket Config Settings

AbsoluteTimeout:   Determines whether timeouts are inactivity timeouts or absolute timeouts.

If AbsoluteTimeout is set to True, any method that does not complete within timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

Note: This option is not valid for User Datagram Protocol (UDP) ports.

Determines whether timeouts are inactivity timeouts or absolute timeouts.

If AbsoluteTimeout is set to True, any method that does not complete within timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

Note: This option is not valid for User Datagram Protocol (UDP) ports.

AbsoluteTimeout:   Determines whether timeouts are inactivity timeouts or absolute timeouts.

If AbsoluteTimeout is set to True, any method that does not complete within timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

Note: This option is not valid for User Datagram Protocol (UDP) ports.

Determines whether timeouts are inactivity timeouts or absolute timeouts.

If AbsoluteTimeout is set to True, any method that does not complete within timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

Note: This option is not valid for User Datagram Protocol (UDP) ports.

FirewallData:   Used to send extra data to the firewall.

When the firewall is a tunneling proxy, use this property to send custom (additional) headers to the firewall (e.g., headers for custom authentication schemes). Used to send extra data to the firewall.

When the firewall is a tunneling proxy, use this property to send custom (additional) headers to the firewall (e.g., headers for custom authentication schemes).

FirewallData:   Used to send extra data to the firewall.

When the firewall is a tunneling proxy, use this property to send custom (additional) headers to the firewall (e.g., headers for custom authentication schemes). Used to send extra data to the firewall.

When the firewall is a tunneling proxy, use this property to send custom (additional) headers to the firewall (e.g., headers for custom authentication schemes).

InBufferSize:   The size in bytes of the incoming queue of the socket.

This is the size of an internal queue in the Transmission Control Protocol (TCP)/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. In some cases, increasing the value of the InBufferSize setting can provide significant improvements in performance.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the class is activated the InBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

The size in bytes of the incoming queue of the socket.

This is the size of an internal queue in the Transmission Control Protocol (TCP)/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. In some cases, increasing the value of the InBufferSize setting can provide significant improvements in performance.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the class is activated the InBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

InBufferSize:   The size in bytes of the incoming queue of the socket.

This is the size of an internal queue in the Transmission Control Protocol (TCP)/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. In some cases, increasing the value of the InBufferSize setting can provide significant improvements in performance.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the class is activated the InBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

The size in bytes of the incoming queue of the socket.

This is the size of an internal queue in the Transmission Control Protocol (TCP)/IP stack. You can increase or decrease its size depending on the amount of data that you will be receiving. In some cases, increasing the value of the InBufferSize setting can provide significant improvements in performance.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the class is activated the InBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

OutBufferSize:   The size in bytes of the outgoing queue of the socket.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be sending. In some cases, increasing the value of the OutBufferSize setting can provide significant improvements in performance.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the class is activated the OutBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

The size in bytes of the outgoing queue of the socket.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be sending. In some cases, increasing the value of the OutBufferSize setting can provide significant improvements in performance.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the class is activated the OutBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

OutBufferSize:   The size in bytes of the outgoing queue of the socket.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be sending. In some cases, increasing the value of the OutBufferSize setting can provide significant improvements in performance.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the class is activated the OutBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

The size in bytes of the outgoing queue of the socket.

This is the size of an internal queue in the TCP/IP stack. You can increase or decrease its size depending on the amount of data that you will be sending. In some cases, increasing the value of the OutBufferSize setting can provide significant improvements in performance.

Some TCP/IP implementations do not support variable buffer sizes. If that is the case, when the class is activated the OutBufferSize reverts to its defined size. The same happens if you attempt to make it too large or too small.

TCPClient Config Settings

ConnectionTimeout:   Sets a separate timeout value for establishing a connection.

When set, this configuration setting allows you to specify a different timeout value for establishing a connection. Otherwise, the class will use timeout for establishing a connection and transmitting/receiving data.

FirewallAutoDetect:   Tells the class whether or not to automatically detect and use firewall system settings, if available.

This configuration setting is provided for use by classs that do not directly expose Firewall properties.

FirewallHost:   Name or IP address of firewall (optional).

If a FirewallHost is given, requested connections will be authenticated through the specified firewall when connecting.

If the FirewallHost setting is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, the FirewallHost setting is set to the corresponding address. If the search is not successful, an error is returned.

Note: This setting is provided for use by classs that do not directly expose Firewall properties.

FirewallPassword:   Password to be used if authentication is to be used when connecting through the firewall.

If FirewallHost is specified, the FirewallUser and FirewallPassword settings are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

Note: This setting is provided for use by classs that do not directly expose Firewall properties.

FirewallPort:   The TCP port for the FirewallHost;.

The FirewallPort is set automatically when FirewallType is set to a valid value.

Note: This configuration setting is provided for use by classs that do not directly expose Firewall properties.

FirewallType:   Determines the type of firewall to connect through.

The appropriate values are as follows:

0No firewall (default setting).
1Connect through a tunneling proxy. FirewallPort is set to 80.
2Connect through a SOCKS4 Proxy. FirewallPort is set to 1080.
3Connect through a SOCKS5 Proxy. FirewallPort is set to 1080.
10Connect through a SOCKS4A Proxy. FirewallPort is set to 1080.

Note: This setting is provided for use by classs that do not directly expose Firewall properties.

FirewallUser:   A user name if authentication is to be used connecting through a firewall.

If the FirewallHost is specified, the FirewallUser and FirewallPassword settings are used to connect and authenticate to the Firewall. If the authentication fails, the class fails with an error.

Note: This setting is provided for use by classs that do not directly expose Firewall properties.

KeepAliveInterval:   The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received.

When set, TCPKeepAlive will automatically be set to True. A TCP keep-alive packet will be sent after a period of inactivity as defined by KeepAliveTime. If no acknowledgment is received from the remote host, the keep-alive packet will be sent again. This configuration setting specifies the interval at which the successive keep-alive packets are sent in milliseconds. This system default if this value is not specified here is 1 second.

Note: This value is not applicable in macOS.

KeepAliveTime:   The inactivity time in milliseconds before a TCP keep-alive packet is sent.

When set, TCPKeepAlive will automatically be set to True. By default, the operating system will determine the time a connection is idle before a Transmission Control Protocol (TCP) keep-alive packet is sent. This system default if this value is not specified here is 2 hours. In many cases, a shorter interval is more useful. Set this value to the desired interval in milliseconds.

Linger:   When set to True, connections are terminated gracefully.

This property controls how a connection is closed. The default is True.

In the case that Linger is True (default), two scenarios determine how long the connection will linger. In the first, if LingerTime is 0 (default), the system will attempt to send pending data for a connection until the default IP timeout expires.

In the second scenario, if LingerTime is a positive value, the system will attempt to send pending data until the specified LingerTime is reached. If this attempt fails, then the system will reset the connection.

The default behavior (which is also the default mode for stream sockets) might result in a long delay in closing the connection. Although the class returns control immediately, the system could hold system resources until all pending data are sent (even after your application closes).

Setting this property to False forces an immediate disconnection. If you know that the other side has received all the data you sent (e.g., by a client acknowledgment), setting this property to False might be the appropriate course of action.

LingerTime:   Time in seconds to have the connection linger.

LingerTime is the time, in seconds, the socket connection will linger. This value is 0 by default, which means it will use the default IP timeout.

LocalHost:   The name of the local host through which connections are initiated or accepted.

The local_host setting contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface), setting LocalHost to the value of an interface will make the class initiate connections (or accept in the case of server classs) only through that interface.

If the class is connected, the local_host setting shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

LocalPort:   The port in the local host where the class binds.

This configuration setting must be set before a connection is attempted. It instructs the class to bind to a specific port (or communication endpoint) in the local machine.

Setting this to 0 (default) enables the system to choose a port at random. The chosen port will be shown by local_port after the connection is established.

local_port cannot be changed once a connection is made. Any attempt to set this when a connection is active will generate an error.

This configuration setting is useful when trying to connect to services that require a trusted port on the client side. An example is the remote shell (rsh) service in UNIX systems.

MaxLineLength:   The maximum amount of data to accumulate when no EOL is found.

MaxLineLength is the size of an internal buffer, which holds received data while waiting for an eol string.

If an eol string is found in the input stream before MaxLineLength bytes are received, the on_data_in event is fired with the EOL parameter set to True, and the buffer is reset.

If no eol is found, and MaxLineLength bytes are accumulated in the buffer, the on_data_in event is fired with the EOL parameter set to False, and the buffer is reset.

The minimum value for MaxLineLength is 256 bytes. The default value is 2048 bytes.

MaxTransferRate:   The transfer rate limit in bytes per second.

This configuration setting can be used to throttle outbound TCP traffic. Set this to the number of bytes to be sent per second. By default, this is not set and there is no limit.

ProxyExceptionsList:   A semicolon separated list of hosts and IPs to bypass when using a proxy.

This configuration setting optionally specifies a semicolon-separated list of hostnames or IP addresses to bypass when a proxy is in use. When requests are made to hosts specified in this property, the proxy will not be used. For instance:

www.google.com;www.nsoftware.com

TCPKeepAlive:   Determines whether or not the keep alive socket option is enabled.

If set to True, the socket's keep-alive option is enabled and keep-alive packets will be sent periodically to maintain the connection. Set KeepAliveTime and KeepAliveInterval to configure the timing of the keep-alive packets.

Note: This value is not applicable in Java.

TcpNoDelay:   Whether or not to delay when sending packets.

When set to True, the socket will send all data that are ready to send at once. When set to False, the socket will send smaller buffered packets of data at small intervals. This is known as the Nagle algorithm.

By default, this configuration setting is set to False.

UseIPv6:   Whether to use IPv6.

When set to 0 (default), the class will use IPv4 exclusively. When set to 1, the class will use IPv6 exclusively. To instruct the class to prefer IPv6 addresses, but use IPv4 if IPv6 is not supported on the system, this setting should be set to 2. The default value is 0. Possible values are as follows:

0 IPv4 only
1 IPv6 only
2 IPv6 with IPv4 fallback

SSL Config Settings

LogSSLPackets:   Controls whether SSL packets are logged when using the internal security API.

When ssl_provider is set to Internal, this configuration setting controls whether Secure Sockets Layer (SSL) packets should be logged. By default, this configuration setting is False, as it is useful only for debugging purposes.

When enabled, SSL packet logs are output using the on_ssl_status event, which will fire each time an SSL packet is sent or received.

Enabling this configuration setting has no effect if ssl_provider is set to Platform.

OpenSSLCADir:   The path to a directory containing CA certificates.

This functionality is available only when the provider is OpenSSL.

The path set by this property should point to a directory containing CA certificates in PEM format. The files each contain one CA certificate. The files are looked up by the CA subject name hash value, which must hence be available. If more than one CA certificate with the same name hash value exist, the extension must be different (e.g., 9d66eef0.0, 9d66eef0.1). OpenSSL recommends the use of the c_rehash utility to create the necessary links. Please refer to the OpenSSL man page SSL_CTX_load_verify_locations(3) for details.

OpenSSLCAFile:   Name of the file containing the list of CA's trusted by your application.

This functionality is available only when the provider is OpenSSL.

The file set by this property should contain a list of CA certificates in PEM format. The file can contain several CA certificates identified by the following sequences:

-----BEGIN CERTIFICATE-----

... (CA certificate in base64 encoding) ...

-----END CERTIFICATE-----

Before, between, and after the certificate text is allowed, which can be used, for example, for descriptions of the certificates. Refer to the OpenSSL man page SSL_CTX_load_verify_locations(3) for details.

OpenSSLCipherList:   A string that controls the ciphers to be used by SSL.

This functionality is available only when the provider is OpenSSL.

The format of this string is described in the OpenSSL man page ciphers(1) section "CIPHER LIST FORMAT". Please refer to it for details. The default string "DEFAULT" is determined at compile time and is normally equivalent to "ALL:!ADH:RC4+RSA:+SSLv2:@STRENGTH".

OpenSSLPrngSeedData:   The data to seed the pseudo random number generator (PRNG).

This functionality is available only when the provider is OpenSSL.

By default, OpenSSL uses the device file "/dev/urandom" to seed the PRNG, and setting OpenSSLPrngSeedData is not required. If set, the string specified is used to seed the PRNG.

ReuseSSLSession:   Determines if the SSL session is reused.

If set to True, the class will reuse the context if and only if the following criteria are met:

  • The target host name is the same.
  • The system cache entry has not expired (default timeout is 10 hours).
  • The application process that calls the function is the same.
  • The logon session is the same.
  • The instance of the class is the same.

SSLCACertFilePaths:   The paths to CA certificate files on Unix/Linux.

This configuration setting specifies the paths on disk to CA certificate files on Unix/Linux.

The value is formatted as a list of paths separated by semicolons. The class will check for the existence of each file in the order specified. When a file is found, the CA certificates within the file will be loaded and used to determine the validity of server or client certificates.

The default value is as follows:

/etc/ssl/ca-bundle.pem;/etc/pki/tls/certs/ca-bundle.crt;/etc/ssl/certs/ca-certificates.crt;/etc/pki/tls/cacert.pem

SSLCACerts:   A newline separated list of CA certificate to be included when performing an SSL handshake.

When ssl_provider is set to Internal, this configuration setting specifies one or more CA certificates to be included with the ssl_cert property. Some servers or clients require the entire chain, including CA certificates, to be presented when performing SSL authentication. The value of this configuration setting is a newline-separated (CR/LF) list of certificates. For instance:

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermedaite Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

SSLCheckCRL:   Whether to check the Certificate Revocation List for the server certificate.

This configuration setting specifies whether the class will check the Certificate Revocation List (CRL) specified by the server certificate. If set to 1 or 2, the class will first obtain the list of CRL URLs from the server certificate's CRL distribution points extension. The class will then make HTTP requests to each CRL endpoint to check the validity of the server's certificate. If the certificate has been revoked or any other issues are found during validation the class fails with an error.

When set to 0 (default), the CRL check will not be performed by the class. When set to 1, it will attempt to perform the CRL check, but it will continue without an error if the server's certificate does not support CRL. When set to 2, it will perform the CRL check and will throw an error if CRL is not supported.

This configuration setting is supported only in the Java, C#, and C++ editions. In the C++ edition, it is supported only on Windows operating systems.

SSLCheckOCSP:   Whether to use OCSP to check the status of the server certificate.

This configuration setting specifies whether the class will use OCSP to check the validity of the server certificate. If set to 1 or 2, the class will first obtain the Online Certificate Status Protocol (OCSP) URL from the server certificate's OCSP extension. The class will then locate the issuing certificate and make an HTTP request to the OCSP endpoint to check the validity of the server's certificate. If the certificate has been revoked or any other issues are found during validation, the class fails with an error.

When set to 0 (default), the class will not perform an OCSP check. When set to 1, it will attempt to perform the OCSP check, but it will continue without an error if the server's certificate does not support OCSP. When set to 2, it will perform the OCSP check and will throw an error if OCSP is not supported.

This configuration setting is supported only in the Java, C#, and C++ editions. In the C++ edition, it is supported only on Windows operating systems.

SSLCipherStrength:   The minimum cipher strength used for bulk encryption.

This minimum cipher strength is largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Note: This configuration setting contains the minimum cipher strength requested from the security library. The actual cipher strength used for the connection is shown by the on_ssl_status event.

Use this configuration setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.

When the provider is OpenSSL, SSLCipherStrength is currently not supported. This functionality is instead made available through the OpenSSLCipherList configuration setting.

SSLClientCACerts:   A newline separated list of CA certificates to use during SSL client certificate validation.

This configuration setting is only applicable to server components (e.g., TCPServer) see SSLServerCACerts for client components (e.g., TCPClient). This setting can be used to optionally specify one or more CA certificates to be used when verifying the client certificate that is presented by the client during the SSL handshake when ssl_authenticate_clients is enabled. When verifying the client's certificate, the certificates trusted by the system will be used as part of the verification process. If the client's CA certificates are not installed to the trusted system store, they may be specified here so they are included when performing the verification process. This configuration setting should be set only if the client's CA certificates are not already trusted on the system and cannot be installed to the trusted system store.

The value of this configuration setting is a newline-separated (CR/LF) list of certificates. For instance:

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert ...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert ...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

SSLEnabledCipherSuites:   The cipher suite to be used in an SSL negotiation.

This configuration setting enables the cipher suites to be used in SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the class will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when ssl_provider is set to Platform include the following: obj.config("SSLEnabledCipherSuites=*"); obj.config("SSLEnabledCipherSuites=CALG_AES_256"); obj.config("SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES"); Possible values when ssl_provider is set to Platform include the following:

  • CALG_3DES
  • CALG_3DES_112
  • CALG_AES
  • CALG_AES_128
  • CALG_AES_192
  • CALG_AES_256
  • CALG_AGREEDKEY_ANY
  • CALG_CYLINK_MEK
  • CALG_DES
  • CALG_DESX
  • CALG_DH_EPHEM
  • CALG_DH_SF
  • CALG_DSS_SIGN
  • CALG_ECDH
  • CALG_ECDH_EPHEM
  • CALG_ECDSA
  • CALG_ECMQV
  • CALG_HASH_REPLACE_OWF
  • CALG_HUGHES_MD5
  • CALG_HMAC
  • CALG_KEA_KEYX
  • CALG_MAC
  • CALG_MD2
  • CALG_MD4
  • CALG_MD5
  • CALG_NO_SIGN
  • CALG_OID_INFO_CNG_ONLY
  • CALG_OID_INFO_PARAMETERS
  • CALG_PCT1_MASTER
  • CALG_RC2
  • CALG_RC4
  • CALG_RC5
  • CALG_RSA_KEYX
  • CALG_RSA_SIGN
  • CALG_SCHANNEL_ENC_KEY
  • CALG_SCHANNEL_MAC_KEY
  • CALG_SCHANNEL_MASTER_HASH
  • CALG_SEAL
  • CALG_SHA
  • CALG_SHA1
  • CALG_SHA_256
  • CALG_SHA_384
  • CALG_SHA_512
  • CALG_SKIPJACK
  • CALG_SSL2_MASTER
  • CALG_SSL3_MASTER
  • CALG_SSL3_SHAMD5
  • CALG_TEK
  • CALG_TLS1_MASTER
  • CALG_TLS1PRF
Example values when ssl_provider is set to Internalinclude the following: obj.config("SSLEnabledCipherSuites=*"); obj.config("SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA"); obj.config("SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_ECDH_RSA_WITH_AES_128_CBC_SHA"); Possible values when ssl_provider is set to Internal include the following:
  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_256_GCM_SHA384
  • TLS_RSA_WITH_AES_128_GCM_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384
  • TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
  • TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
  • TLS_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_256_CBC_SHA
  • TLS_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
  • TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
  • TLS_DHE_DSS_WITH_AES_128_CBC_SHA
  • TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
  • TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_3DES_EDE_CBC_SHA
  • TLS_RSA_WITH_DES_CBC_SHA
  • TLS_DHE_RSA_WITH_DES_CBC_SHA
  • TLS_DHE_DSS_WITH_DES_CBC_SHA
  • TLS_RSA_WITH_RC4_128_MD5
  • TLS_RSA_WITH_RC4_128_SHA

When TLS 1.3 is negotiated (see SSLEnabledProtocols), only the following cipher suites are supported:

  • TLS_AES_256_GCM_SHA384
  • TLS_CHACHA20_POLY1305_SHA256
  • TLS_AES_128_GCM_SHA256

SSLEnabledCipherSuites is used together with SSLCipherStrength.

SSLEnabledProtocols:   Used to enable/disable the supported security protocols.

This configuration setting is used to enable or disable the supported security protocols.

Not all supported protocols are enabled by default. The default value is 4032 for client components, and 3072 for server components. To specify a combination of enabled protocol versions set this config to the binary OR of one or more of the following values:

TLS1.312288 (Hex 3000)
TLS1.23072 (Hex C00) (Default - Client and Server)
TLS1.1768 (Hex 300) (Default - Client)
TLS1 192 (Hex C0) (Default - Client)
SSL3 48 (Hex 30)
SSL2 12 (Hex 0C)

Note that only TLS 1.2 is enabled for server components that accept incoming connections. This adheres to industry standards to ensure a secure connection. Client components enable TLS 1.0, TLS 1.1, and TLS 1.2 by default and will negotiate the highest mutually supported version when connecting to a server, which should be TLS 1.2 in most cases.

SSLEnabledProtocols: Transport Layer Security (TLS) 1.3 Notes:

By default when TLS 1.3 is enabled, the class will use the internal TLS implementation when the ssl_provider is set to Automatic for all editions.

In editions that are designed to run on Windows, ssl_provider can be set to Platform to use the platform implementation instead of the internal implementation. When configured in this manner, please note that the platform provider is supported only on Windows 11/Windows Server 2022 and up. The default internal provider is available on all platforms and is not restricted to any specific OS version.

If set to 1 (Platform provider), please be aware of the following notes:

  • The platform provider is available only on Windows 11/Windows Server 2022 and up.
  • SSLEnabledCipherSuites and other similar SSL configuration settings are not supported.
  • If SSLEnabledProtocols includes both TLS 1.3 and TLS 1.2, these restrictions are still applicable even if TLS 1.2 is negotiated. Enabling TLS 1.3 with the platform provider changes the implementation used for all TLS versions.

SSLEnabledProtocols: SSL2 and SSL3 Notes:

SSL 2.0 and 3.0 are not supported by the class when the ssl_provider is set to internal. To use SSL 2.0 or SSL 3.0, the platform security API must have the protocols enabled and ssl_provider needs to be set to platform.

SSLEnableRenegotiation:   Whether the renegotiation_info SSL extension is supported.

This configuration setting specifies whether the renegotiation_info SSL extension will be used in the request when using the internal security API. This configuration setting is False by default, but it can be set to True to enable the extension.

This configuration setting is applicable only when ssl_provider is set to Internal.

SSLIncludeCertChain:   Whether the entire certificate chain is included in the SSLServerAuthentication event.

This configuration setting specifies whether the Encoded parameter of the on_ssl_server_authentication event contains the full certificate chain. By default this value is False and only the leaf certificate will be present in the Encoded parameter of the on_ssl_server_authentication event.

If set to True, all certificates returned by the server will be present in the Encoded parameter of the on_ssl_server_authentication event. This includes the leaf certificate, any intermediate certificate, and the root certificate.

SSLKeyLogFile:   The location of a file where per-session secrets are written for debugging purposes.

This configuration setting optionally specifies the full path to a file on disk where per-session secrets are stored for debugging purposes.

When set, the class will save the session secrets in the same format as the SSLKEYLOGFILE environment variable functionality used by most major browsers and tools, such as Chrome, Firefox, and cURL. This file can then be used in tools such as Wireshark to decrypt TLS traffic for debugging purposes. When writing to this file, the class will only append, it will not overwrite previous values.

Note: This configuration setting is applicable only when ssl_provider is set to Internal.

SSLNegotiatedCipher:   Returns the negotiated cipher suite.

This configuration setting returns the cipher suite negotiated during the SSL handshake.

Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedCipher[connId]");

SSLNegotiatedCipherStrength:   Returns the negotiated cipher suite strength.

This configuration setting returns the strength of the cipher suite negotiated during the SSL handshake.

Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedCipherStrength[connId]");

SSLNegotiatedCipherSuite:   Returns the negotiated cipher suite.

This configuration setting returns the cipher suite negotiated during the SSL handshake represented as a single string.

Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedCipherSuite[connId]");

SSLNegotiatedKeyExchange:   Returns the negotiated key exchange algorithm.

This configuration setting returns the key exchange algorithm negotiated during the SSL handshake.

Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedKeyExchange[connId]");

SSLNegotiatedKeyExchangeStrength:   Returns the negotiated key exchange algorithm strength.

This configuration setting returns the strength of the key exchange algorithm negotiated during the SSL handshake.

Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedKeyExchangeStrength[connId]");

SSLNegotiatedVersion:   Returns the negotiated protocol version.

This configuration setting returns the protocol version negotiated during the SSL handshake.

Note: For server components (e.g., TCPServer), this is a per-connection configuration setting accessed by passing the ConnectionId. For example: server.Config("SSLNegotiatedVersion[connId]");

SSLSecurityFlags:   Flags that control certificate verification.

The following flags are defined (specified in hexadecimal notation). They can be ORed together to exclude multiple conditions:

0x00000001Ignore time validity status of certificate.
0x00000002Ignore time validity status of CTL.
0x00000004Ignore non-nested certificate times.
0x00000010Allow unknown certificate authority.
0x00000020Ignore wrong certificate usage.
0x00000100Ignore unknown certificate revocation status.
0x00000200Ignore unknown CTL signer revocation status.
0x00000400Ignore unknown certificate authority revocation status.
0x00000800Ignore unknown root revocation status.
0x00008000Allow test root certificate.
0x00004000Trust test root certificate.
0x80000000Ignore non-matching CN (certificate CN non-matching server name).

This functionality is currently not available when the provider is OpenSSL.

SSLServerCACerts:   A newline separated list of CA certificates to use during SSL server certificate validation.

This configuration setting is only used by client components (e.g., TCPClient) see SSLClientCACerts for server components (e.g., TCPServer). This configuration setting can be used to optionally specify one or more CA certificates to be used when connecting to the server and verifying the server certificate. When verifying the server's certificate, the certificates trusted by the system will be used as part of the verification process. If the server's CA certificates are not installed to the trusted system store, they may be specified here so they are included when performing the verification process. This configuration setting should be set only if the server's CA certificates are not already trusted on the system and cannot be installed to the trusted system store.

The value of this configuration setting is a newline-separated (CR/LF) list of certificates. For instance:

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
... Intermediate Cert...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
... Root Cert...
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

TLS12SignatureAlgorithms:   Defines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal.

This configuration setting specifies the allowed server certificate signature algorithms when ssl_provider is set to Internal and SSLEnabledProtocols is set to allow TLS 1.2.

When specified the class will verify that the server certificate signature algorithm is among the values specified in this configuration setting. If the server certificate signature algorithm is unsupported, the class fails with an error.

The format of this value is a comma-separated list of hash-signature combinations. For instance: component.SSLProvider = TCPClientSSLProviders.sslpInternal; component.Config("SSLEnabledProtocols=3072"); //TLS 1.2 component.Config("TLS12SignatureAlgorithms=sha256-rsa,sha256-dsa,sha1-rsa,sha1-dsa"); The default value for this configuration setting is sha512-ecdsa,sha512-rsa,sha512-dsa,sha384-ecdsa,sha384-rsa,sha384-dsa,sha256-ecdsa,sha256-rsa,sha256-dsa,sha224-ecdsa,sha224-rsa,sha224-dsa,sha1-ecdsa,sha1-rsa,sha1-dsa.

To not restrict the server's certificate signature algorithm, specify an empty string as the value for this configuration setting, which will cause the signature_algorithms TLS 1.2 extension to not be sent.

TLS12SupportedGroups:   The supported groups for ECC.

This configuration setting specifies a comma-separated list of named groups used in TLS 1.2 for ECC.

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1.

When using TLS 1.2 and ssl_provider is set to Internal, the values refer to the supported groups for ECC. The following values are supported:

  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)

TLS13KeyShareGroups:   The groups for which to pregenerate key shares.

This configuration setting specifies a comma-separated list of named groups used in TLS 1.3 for key exchange. The groups specified here will have key share data pregenerated locally before establishing a connection. This can prevent an additional roundtrip during the handshake if the group is supported by the server.

The default value is set to balance common supported groups and the computational resources required to generate key shares. As a result, only some groups are included by default in this configuration setting.

Note: All supported groups can always be used during the handshake even if not listed here, but if a group is used that is not present in this list, it will incur an additional roundtrip and time to generate the key share for that group.

In most cases, this configuration setting does not need to be modified. This should be modified only if there is a specific reason to do so.

The default value is ecdhe_x25519,ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_x25519" (default)
  • "ecdhe_x448"
  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1"
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096"
  • "ffdhe_6144"
  • "ffdhe_8192"

TLS13SignatureAlgorithms:   The allowed certificate signature algorithms.

This configuration setting holds a comma-separated list of allowed signature algorithms. Possible values include the following:

  • "ed25519" (default)
  • "ed448" (default)
  • "ecdsa_secp256r1_sha256" (default)
  • "ecdsa_secp384r1_sha384" (default)
  • "ecdsa_secp521r1_sha512" (default)
  • "rsa_pkcs1_sha256" (default)
  • "rsa_pkcs1_sha384" (default)
  • "rsa_pkcs1_sha512" (default)
  • "rsa_pss_sha256" (default)
  • "rsa_pss_sha384" (default)
  • "rsa_pss_sha512" (default)
The default value is rsa_pss_sha256,rsa_pss_sha384,rsa_pss_sha512,rsa_pkcs1_sha256,rsa_pkcs1_sha384,rsa_pkcs1_sha512,ecdsa_secp256r1_sha256,ecdsa_secp384r1_sha384,ecdsa_secp521r1_sha512,ed25519,ed448. This configuration setting is applicable only when SSLEnabledProtocols includes TLS 1.3.
TLS13SupportedGroups:   The supported groups for (EC)DHE key exchange.

This configuration setting specifies a comma-separated list of named groups used in TLS 1.3 for key exchange. This configuration setting should be modified only if there is a specific reason to do so.

The default value is ecdhe_x25519,ecdhe_x448,ecdhe_secp256r1,ecdhe_secp384r1,ecdhe_secp521r1,ffdhe_2048,ffdhe_3072,ffdhe_4096,ffdhe_6144,ffdhe_8192

The values are ordered from most preferred to least preferred. The following values are supported:

  • "ecdhe_x25519" (default)
  • "ecdhe_x448" (default)
  • "ecdhe_secp256r1" (default)
  • "ecdhe_secp384r1" (default)
  • "ecdhe_secp521r1" (default)
  • "ffdhe_2048" (default)
  • "ffdhe_3072" (default)
  • "ffdhe_4096" (default)
  • "ffdhe_6144" (default)
  • "ffdhe_8192" (default)

Base Config Settings

BuildInfo:   Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

CodePage:   The system code page used for Unicode to Multibyte translations.

The default code page is Unicode UTF-8 (65001).

The following is a list of valid code page identifiers:

IdentifierName
037IBM EBCDIC - U.S./Canada
437OEM - United States
500IBM EBCDIC - International
708Arabic - ASMO 708
709Arabic - ASMO 449+, BCON V4
710Arabic - Transparent Arabic
720Arabic - Transparent ASMO
737OEM - Greek (formerly 437G)
775OEM - Baltic
850OEM - Multilingual Latin I
852OEM - Latin II
855OEM - Cyrillic (primarily Russian)
857OEM - Turkish
858OEM - Multilingual Latin I + Euro symbol
860OEM - Portuguese
861OEM - Icelandic
862OEM - Hebrew
863OEM - Canadian-French
864OEM - Arabic
865OEM - Nordic
866OEM - Russian
869OEM - Modern Greek
870IBM EBCDIC - Multilingual/ROECE (Latin-2)
874ANSI/OEM - Thai (same as 28605, ISO 8859-15)
875IBM EBCDIC - Modern Greek
932ANSI/OEM - Japanese, Shift-JIS
936ANSI/OEM - Simplified Chinese (PRC, Singapore)
949ANSI/OEM - Korean (Unified Hangul Code)
950ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC)
1026IBM EBCDIC - Turkish (Latin-5)
1047IBM EBCDIC - Latin 1/Open System
1140IBM EBCDIC - U.S./Canada (037 + Euro symbol)
1141IBM EBCDIC - Germany (20273 + Euro symbol)
1142IBM EBCDIC - Denmark/Norway (20277 + Euro symbol)
1143IBM EBCDIC - Finland/Sweden (20278 + Euro symbol)
1144IBM EBCDIC - Italy (20280 + Euro symbol)
1145IBM EBCDIC - Latin America/Spain (20284 + Euro symbol)
1146IBM EBCDIC - United Kingdom (20285 + Euro symbol)
1147IBM EBCDIC - France (20297 + Euro symbol)
1148IBM EBCDIC - International (500 + Euro symbol)
1149IBM EBCDIC - Icelandic (20871 + Euro symbol)
1200Unicode UCS-2 Little-Endian (BMP of ISO 10646)
1201Unicode UCS-2 Big-Endian
1250ANSI - Central European
1251ANSI - Cyrillic
1252ANSI - Latin I
1253ANSI - Greek
1254ANSI - Turkish
1255ANSI - Hebrew
1256ANSI - Arabic
1257ANSI - Baltic
1258ANSI/OEM - Vietnamese
1361Korean (Johab)
10000MAC - Roman
10001MAC - Japanese
10002MAC - Traditional Chinese (Big5)
10003MAC - Korean
10004MAC - Arabic
10005MAC - Hebrew
10006MAC - Greek I
10007MAC - Cyrillic
10008MAC - Simplified Chinese (GB 2312)
10010MAC - Romania
10017MAC - Ukraine
10021MAC - Thai
10029MAC - Latin II
10079MAC - Icelandic
10081MAC - Turkish
10082MAC - Croatia
12000Unicode UCS-4 Little-Endian
12001Unicode UCS-4 Big-Endian
20000CNS - Taiwan
20001TCA - Taiwan
20002Eten - Taiwan
20003IBM5550 - Taiwan
20004TeleText - Taiwan
20005Wang - Taiwan
20105IA5 IRV International Alphabet No. 5 (7-bit)
20106IA5 German (7-bit)
20107IA5 Swedish (7-bit)
20108IA5 Norwegian (7-bit)
20127US-ASCII (7-bit)
20261T.61
20269ISO 6937 Non-Spacing Accent
20273IBM EBCDIC - Germany
20277IBM EBCDIC - Denmark/Norway
20278IBM EBCDIC - Finland/Sweden
20280IBM EBCDIC - Italy
20284IBM EBCDIC - Latin America/Spain
20285IBM EBCDIC - United Kingdom
20290IBM EBCDIC - Japanese Katakana Extended
20297IBM EBCDIC - France
20420IBM EBCDIC - Arabic
20423IBM EBCDIC - Greek
20424IBM EBCDIC - Hebrew
20833IBM EBCDIC - Korean Extended
20838IBM EBCDIC - Thai
20866Russian - KOI8-R
20871IBM EBCDIC - Icelandic
20880IBM EBCDIC - Cyrillic (Russian)
20905IBM EBCDIC - Turkish
20924IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol)
20932JIS X 0208-1990 & 0121-1990
20936Simplified Chinese (GB2312)
21025IBM EBCDIC - Cyrillic (Serbian, Bulgarian)
21027Extended Alpha Lowercase
21866Ukrainian (KOI8-U)
28591ISO 8859-1 Latin I
28592ISO 8859-2 Central Europe
28593ISO 8859-3 Latin 3
28594ISO 8859-4 Baltic
28595ISO 8859-5 Cyrillic
28596ISO 8859-6 Arabic
28597ISO 8859-7 Greek
28598ISO 8859-8 Hebrew
28599ISO 8859-9 Latin 5
28605ISO 8859-15 Latin 9
29001Europa 3
38598ISO 8859-8 Hebrew
50220ISO 2022 Japanese with no halfwidth Katakana
50221ISO 2022 Japanese with halfwidth Katakana
50222ISO 2022 Japanese JIS X 0201-1989
50225ISO 2022 Korean
50227ISO 2022 Simplified Chinese
50229ISO 2022 Traditional Chinese
50930Japanese (Katakana) Extended
50931US/Canada and Japanese
50933Korean Extended and Korean
50935Simplified Chinese Extended and Simplified Chinese
50936Simplified Chinese
50937US/Canada and Traditional Chinese
50939Japanese (Latin) Extended and Japanese
51932EUC - Japanese
51936EUC - Simplified Chinese
51949EUC - Korean
51950EUC - Traditional Chinese
52936HZ-GB2312 Simplified Chinese
54936Windows XP: GB18030 Simplified Chinese (4 Byte)
57002ISCII Devanagari
57003ISCII Bengali
57004ISCII Tamil
57005ISCII Telugu
57006ISCII Assamese
57007ISCII Oriya
57008ISCII Kannada
57009ISCII Malayalam
57010ISCII Gujarati
57011ISCII Punjabi
65000Unicode UTF-7
65001Unicode UTF-8
The following is a list of valid code page identifiers for Mac OS only:
IdentifierName
1ASCII
2NEXTSTEP
3JapaneseEUC
4UTF8
5ISOLatin1
6Symbol
7NonLossyASCII
8ShiftJIS
9ISOLatin2
10Unicode
11WindowsCP1251
12WindowsCP1252
13WindowsCP1253
14WindowsCP1254
15WindowsCP1250
21ISO2022JP
30MacOSRoman
10UTF16String
0x90000100UTF16BigEndian
0x94000100UTF16LittleEndian
0x8c000100UTF32String
0x98000100UTF32BigEndian
0x9c000100UTF32LittleEndian
65536Proprietary

LicenseInfo:   Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

  • Product: The product the license is for.
  • Product Key: The key the license was generated from.
  • License Source: Where the license was found (e.g., RuntimeLicense, License File).
  • License Type: The type of license installed (e.g., Royalty Free, Single Server).
  • Last Valid Build: The last valid build number for which the license will work.
MaskSensitiveData:   Whether sensitive data is masked in log messages.

In certain circumstances it may be beneficial to mask sensitive data, like passwords, in log messages. Set this to True to mask sensitive data. The default is True.

This setting only works on these classes: AS3Receiver, AS3Sender, Atom, Client(3DS), FTP, FTPServer, IMAP, OFTPClient, SSHClient, SCP, Server(3DS), Sexec, SFTP, SFTPServer, SSHServer, TCPClient, TCPServer.

ProcessIdleEvents:   Whether the class uses its internal event loop to process events when the main thread is idle.

If set to False, the class will not fire internal idle events. Set this to False to use the class in a background thread on Mac OS. By default, this setting is True.

SelectWaitMillis:   The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.

If there are no events to process when do_events is called, the class will wait for the amount of time specified here before returning. The default value is 20.

UseInternalSecurityAPI:   Whether or not to use the system security libraries or an internal implementation.

When set to False, the class will use the system security libraries by default to perform cryptographic functions where applicable.

Setting this configuration setting to True tells the class to use the internal implementation instead of using the system security libraries.

On Windows, this setting is set to False by default. On Linux/macOS, this setting is set to True by default.

To use the system security libraries for Linux, OpenSSL support must be enabled. For more information on how to enable OpenSSL, please refer to the OpenSSL Notes section.

IPPhone Errors

IPPHONE Errors

201   Timeout error. The error description contains detailed information.
202   Invalid argument error. The error description contains detailed information.
601   Protocol error. The error description contains detailed information.

UDP Errors

104   UDP is already active.
106   You cannot change the local_port while the class is active.
107   You cannot change the local_host at this time. A connection is in progress.
109   The class must be active for this operation.
112   You cannot change MaxPacketSize while the class is active.
113   You cannot change ShareLocalPort option while the class is active.
114   You cannot change remote_host when UseConnection is set and the class active.
115   You cannot change remote_port when UseConnection is set and the class is active.
116   remote_port cannot be zero when UseConnection is set. Please specify a valid service port number.
117   You cannot change UseConnection while the class is active.
118   Message cannot be longer than MaxPacketSize.
119   Message is too short.
434   Unable to convert string to selected CodePage

SSL Errors

270   Cannot load specified security library.
271   Cannot open certificate store.
272   Cannot find specified certificate.
273   Cannot acquire security credentials.
274   Cannot find certificate chain.
275   Cannot verify certificate chain.
276   Error during handshake.
280   Error verifying certificate.
281   Could not find client certificate.
282   Could not find server certificate.
283   Error encrypting data.
284   Error decrypting data.

TCP/IP Errors

10004   [10004] Interrupted system call.
10009   [10009] Bad file number.
10013   [10013] Access denied.
10014   [10014] Bad address.
10022   [10022] Invalid argument.
10024   [10024] Too many open files.
10035   [10035] Operation would block.
10036   [10036] Operation now in progress.
10037   [10037] Operation already in progress.
10038   [10038] Socket operation on nonsocket.
10039   [10039] Destination address required.
10040   [10040] Message is too long.
10041   [10041] Protocol wrong type for socket.
10042   [10042] Bad protocol option.
10043   [10043] Protocol is not supported.
10044   [10044] Socket type is not supported.
10045   [10045] Operation is not supported on socket.
10046   [10046] Protocol family is not supported.
10047   [10047] Address family is not supported by protocol family.
10048   [10048] Address already in use.
10049   [10049] Cannot assign requested address.
10050   [10050] Network is down.
10051   [10051] Network is unreachable.
10052   [10052] Net dropped connection or reset.
10053   [10053] Software caused connection abort.
10054   [10054] Connection reset by peer.
10055   [10055] No buffer space available.
10056   [10056] Socket is already connected.
10057   [10057] Socket is not connected.
10058   [10058] Cannot send after socket shutdown.
10059   [10059] Too many references, cannot splice.
10060   [10060] Connection timed out.
10061   [10061] Connection refused.
10062   [10062] Too many levels of symbolic links.
10063   [10063] File name is too long.
10064   [10064] Host is down.
10065   [10065] No route to host.
10066   [10066] Directory is not empty
10067   [10067] Too many processes.
10068   [10068] Too many users.
10069   [10069] Disc Quota Exceeded.
10070   [10070] Stale NFS file handle.
10071   [10071] Too many levels of remote in path.
10091   [10091] Network subsystem is unavailable.
10092   [10092] WINSOCK DLL Version out of range.
10093   [10093] Winsock is not loaded yet.
11001   [11001] Host not found.
11002   [11002] Nonauthoritative 'Host not found' (try again or check DNS setup).
11003   [11003] Nonrecoverable errors: FORMERR, REFUSED, NOTIMP.
11004   [11004] Valid name, no data record (check DNS setup).