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.
active | The current activation status of the class. |
call_count | The number of records in the Call arrays. |
call_call_id | String representation of an immutable universally unique identifier (UUID) specific to the call. |
call_conference_id | A unique identifier for a conference call. |
call_duration | Elapsed time, in seconds, since the call has begun. |
call_last_status | This property indicates the call's last response code. |
call_local_address | The name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
call_local_port | The UDP port in the local host where UDP binds. |
call_microphone | The microphone currently in use during the call. |
call_mute_microphone | This property can be set to mute the Microphone being used by the class in the given call. |
call_mute_speaker | This property can be set to mute the Speaker being used by the class in the given call. |
call_outgoing | Indicates whether the current call is outgoing. |
call_playing | Indicates whether the current call is playing audio via PlayText or PlayFile , or PlayBytes . |
call_recording | Indicates whether the current call is recording the received voice from the peer. |
call_remote_address | The address of the remote host we are communicating with. |
call_remote_port | The port of the remote host we are communicating with. |
call_remote_uri | This property communicates who to call via SIP. |
call_remote_user | The username or telephone number of the remote user associated with the call. |
call_speaker | The speaker currently in use during the call. |
call_started_at | The number of milliseconds since 12:00:00 AM January 1, 1970 when this call started. |
call_state | This property indicates the state of the current call. |
call_user_input | String representation of digits typed by the callee using their keypad. |
call_via | The Via header sent in the most recent SIP request. |
local_host | This property includes the name of the local host or user-assigned IP interface through which connections are initiated or accepted. |
local_port | This property includes the User Datagram Protocol (UDP) port in the local host where UDP binds. |
microphone_count | The number of records in the Microphone arrays. |
microphone_channels | Number specifying whether the device supports mono (1) or stereo (2) output. |
microphone_manufacturer_id | Manufacturer identifier for the device driver for the device. |
microphone_name | Product name in a null-terminated string. |
microphone_product_id | Product identifier for the device as assigned by Windows. |
microphone_support | Bitmask of optional functionalities supported by the device. |
microphone_supported_formats | Bitmask of standard formats that are supported. |
password | The password that is used when connecting to the SIP Server. |
port | The port on the SIP server the class is connecting to. |
rtp_security_mode | Specifies the security mode that will be used when transmitting RTP. |
server | The address of the SIP Server. |
sip_transport_protocol | Specifies the transport protocol the class will use for SIP signaling. |
speaker_count | The number of records in the Speaker arrays. |
speaker_channels | Number specifying whether the device supports mono (1) or stereo (2) output. |
speaker_manufacturer_id | Manufacturer identifier for the device driver for the device. |
speaker_name | Product name in a null-terminated string. |
speaker_product_id | Product identifier for the device as assigned by Windows. |
speaker_support | Bitmask of optional functionalities supported by the device. |
speaker_supported_formats | Bitmask of standard formats that are supported. |
ssl_accept_server_cert_effective_date | This is the date on which this certificate becomes valid. |
ssl_accept_server_cert_expiration_date | This is the date the certificate expires. |
ssl_accept_server_cert_extended_key_usage | This is a comma-delimited list of extended key usage identifiers. |
ssl_accept_server_cert_fingerprint | This is the hex-encoded, 16-byte MD5 fingerprint of the certificate. |
ssl_accept_server_cert_fingerprint_sha1 | This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate. |
ssl_accept_server_cert_fingerprint_sha256 | This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate. |
ssl_accept_server_cert_issuer | This is the issuer of the certificate. |
ssl_accept_server_cert_private_key | This is the private key of the certificate (if available). |
ssl_accept_server_cert_private_key_available | This property shows whether a PrivateKey is available for the selected certificate. |
ssl_accept_server_cert_private_key_container | This is the name of the PrivateKey container for the certificate (if available). |
ssl_accept_server_cert_public_key | This is the public key of the certificate. |
ssl_accept_server_cert_public_key_algorithm | This property contains the textual description of the certificate's public key algorithm. |
ssl_accept_server_cert_public_key_length | This is the length of the certificate's public key (in bits). |
ssl_accept_server_cert_serial_number | This is the serial number of the certificate encoded as a string. |
ssl_accept_server_cert_signature_algorithm | The property contains the text description of the certificate's signature algorithm. |
ssl_accept_server_cert_store | This is the name of the certificate store for the client certificate. |
ssl_accept_server_cert_store_password | 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 | This is the type of certificate store for this certificate. |
ssl_accept_server_cert_subject_alt_names | This property contains comma-separated lists of alternative subject names for the certificate. |
ssl_accept_server_cert_thumbprint_md5 | This property contains the MD5 hash of the certificate. |
ssl_accept_server_cert_thumbprint_sha1 | This property contains the SHA-1 hash of the certificate. |
ssl_accept_server_cert_thumbprint_sha256 | This property contains the SHA-256 hash of the certificate. |
ssl_accept_server_cert_usage | This property contains the text description of UsageFlags . |
ssl_accept_server_cert_usage_flags | This property contains the flags that show intended use for the certificate. |
ssl_accept_server_cert_version | This property contains the certificate's version number. |
ssl_accept_server_cert_subject | This is the subject of the certificate used for client authentication. |
ssl_accept_server_cert_encoded | This is the certificate (PEM/Base64 encoded). |
ssl_cert_effective_date | This is the date on which this certificate becomes valid. |
ssl_cert_expiration_date | This is the date the certificate expires. |
ssl_cert_extended_key_usage | This is a comma-delimited list of extended key usage identifiers. |
ssl_cert_fingerprint | This is the hex-encoded, 16-byte MD5 fingerprint of the certificate. |
ssl_cert_fingerprint_sha1 | This is the hex-encoded, 20-byte SHA-1 fingerprint of the certificate. |
ssl_cert_fingerprint_sha256 | This is the hex-encoded, 32-byte SHA-256 fingerprint of the certificate. |
ssl_cert_issuer | This is the issuer of the certificate. |
ssl_cert_private_key | This is the private key of the certificate (if available). |
ssl_cert_private_key_available | This property shows whether a PrivateKey is available for the selected certificate. |
ssl_cert_private_key_container | This is the name of the PrivateKey container for the certificate (if available). |
ssl_cert_public_key | This is the public key of the certificate. |
ssl_cert_public_key_algorithm | This property contains the textual description of the certificate's public key algorithm. |
ssl_cert_public_key_length | This is the length of the certificate's public key (in bits). |
ssl_cert_serial_number | This is the serial number of the certificate encoded as a string. |
ssl_cert_signature_algorithm | The property contains the text description of the certificate's signature algorithm. |
ssl_cert_store | This is the name of the certificate store for the client certificate. |
ssl_cert_store_password | 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 | This is the type of certificate store for this certificate. |
ssl_cert_subject_alt_names | This property contains comma-separated lists of alternative subject names for the certificate. |
ssl_cert_thumbprint_md5 | This property contains the MD5 hash of the certificate. |
ssl_cert_thumbprint_sha1 | This property contains the SHA-1 hash of the certificate. |
ssl_cert_thumbprint_sha256 | This property contains the SHA-256 hash of the certificate. |
ssl_cert_usage | This property contains the text description of UsageFlags . |
ssl_cert_usage_flags | This property contains the flags that show intended use for the certificate. |
ssl_cert_version | This property contains the certificate's version number. |
ssl_cert_subject | This is the subject of the certificate used for client authentication. |
ssl_cert_encoded | This is the certificate (PEM/Base64 encoded). |
user | The 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.
activate | Activates the class. |
answer | Answers an incoming phone call. |
config | Sets or retrieves a configuration setting. |
deactivate | Deactivates the class. |
decline | Declines an incoming phone call. |
dial | Used to make a call. |
do_events | This method processes events from the internal message queue. |
forward | Used to forward an incoming call. |
hangup | Used to hang up a specific call. |
hangup_all | Used to hang up all calls. |
hold | Places a call on hold. |
join_conference | Adds a call to a conference call. |
leave_conference | Removes a call from a conference call. |
list_conferences | Lists ongoing conference calls. |
list_microphones | Lists all microphones detected on the system. |
list_speakers | Lists all speakers detected on the system. |
mute_microphone | Used to mute or unmute the microphone for a specified call. |
mute_speaker | Used to mute or unmute the speaker for a specified call. |
ping | Used to ping the server. |
play_bytes | This method is used to play bytes to a call. |
play_file | Plays audio from a WAV file to a call. |
play_text | Plays audio from a string to a call using Text-to-Speech. |
reset | This method will reset the class. |
set_microphone | Sets the microphone used by the class. |
set_speaker | Sets the speaker used by the class. |
start_recording | Used to start recording the audio of a call. |
stop_playing | Stops audio from playing to a call. |
stop_recording | Stops recording the audio of a call. |
transfer | Transfers a call. |
type_digit | Used to type a digit. |
unhold | Takes 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_activated | This event is fired immediately after the class is activated. |
on_call_ready | This event is fired after a call has been answered, declined, or ignored. |
on_call_state_changed | This event is fired after a call's state has changed. |
on_call_terminated | This event is fired after a call has been terminated. |
on_deactivated | This event is fired immediately after the class is deactivated. |
on_dial_completed | This event is fired after the dial process has finished. |
on_digit | This event fires every time a digit is pressed using the keypad. |
on_error | Fired when information is available about errors during data delivery. |
on_incoming_call | This event is fired when an incoming call is received. |
on_log | This event is fired once for each log message. |
on_outgoing_call | This event is fired when an outgoing call has been made. |
on_played | This event is fired after the class finishes playing available audio. |
on_record | This event is fired when recorded audio data is available. |
on_silence | This event is fired when the class detects silence from incoming audio streams. |
on_ssl_server_authentication | Fired after the server presents its certificate to the client. |
on_ssl_status | Fired 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.
AudioDirection | Indicates the direction of available recorded audio when dynamic recording is enabled. |
AuthUser | Specifies the username to be used during client authentication. |
Codecs | Comma-separated list of codecs the class can use. |
DeclineStatus | Specifies the status to send when declining an incoming call. |
DialTimeout | Specifies the amount of time to wait for a response when making a call. |
DialToneFile | Specifies the location of the WAV file to play when making a call. |
DisableRegistration | Can be used to disable SIP registration. |
Domain | Can be used to set the address of the SIP domain. |
DtmfMethod | The method used for delivering the signals/tones sent when typing a digit. |
EnableDynamicRecording | Specifies whether dynamic recording is enabled when recording a call. |
LogEncodedAudioData | Whether the class will log encoded audio data. |
LogLevel | The level of detail that is logged. |
LogRTPPackets | Whether the class will log RTP packets. |
RecordType | The type of recording the class will use. |
RedirectLimit | The maximum number of redirects an outgoing call can experience. |
RefreshInterval | Used to manually specify the interval between subsequent registration messages after successful activation. |
RegistrationInterval | Specifies the lifetime of the current registration. |
RingtoneFile | Specifies location of a WAV file to play when receiving an incoming call. |
SilenceInterval | Specifies the interval the class uses to detect periods of silence. |
STUNPort | The port of the STUN server. |
STUNServer | The address of the STUN Server. |
UnregisterOnActivate | Specifies whether the class will unregister from the SIP Server before registration. |
VoiceIndex | The voice that will be used when playing text. |
VoiceRate | The speaking rate of the voice when playing text. |
CaptureIPPacketInfo | Used to capture the packet information. |
DelayHostResolution | Whether the hostname is resolved when RemoteHost is set. |
DestinationAddress | Used to get the destination address from the packet information. |
DontFragment | Used to set the Don't Fragment flag of outgoing packets. |
LocalHost | The name of the local host through which connections are initiated or accepted. |
LocalPort | The port in the local host where the class binds. |
MaxPacketSize | The maximum length of the packets that can be received. |
QOSDSCPValue | Used to specify an arbitrary QOS/DSCP setting (optional). |
QOSTrafficType | Used to specify QOS/DSCP settings (optional). |
ShareLocalPort | If set to True, allows more than one instance of the class to be active on the same local port. |
SourceIPAddress | Used to set the source IP address used when sending a packet. |
SourceMacAddress | Used to set the source MAC address used when sending a packet. |
UseConnection | Determines whether to use a connected socket. |
UseIPv6 | Whether or not to use IPv6. |
AbsoluteTimeout | Determines whether timeouts are inactivity timeouts or absolute timeouts. |
AbsoluteTimeout | Determines whether timeouts are inactivity timeouts or absolute timeouts. |
FirewallData | Used to send extra data to the firewall. |
FirewallData | Used to send extra data to the firewall. |
InBufferSize | The size in bytes of the incoming queue of the socket. |
InBufferSize | The size in bytes of the incoming queue of the socket. |
OutBufferSize | The size in bytes of the outgoing queue of the socket. |
OutBufferSize | The size in bytes of the outgoing queue of the socket. |
ConnectionTimeout | Sets a separate timeout value for establishing a connection. |
FirewallAutoDetect | Tells the class whether or not to automatically detect and use firewall system settings, if available. |
FirewallHost | Name or IP address of firewall (optional). |
FirewallPassword | Password to be used if authentication is to be used when connecting through the firewall. |
FirewallPort | The TCP port for the FirewallHost;. |
FirewallType | Determines the type of firewall to connect through. |
FirewallUser | A user name if authentication is to be used connecting through a firewall. |
KeepAliveInterval | The retry interval, in milliseconds, to be used when a TCP keep-alive packet is sent and no response is received. |
KeepAliveTime | The inactivity time in milliseconds before a TCP keep-alive packet is sent. |
Linger | When set to True, connections are terminated gracefully. |
LingerTime | Time in seconds to have the connection linger. |
LocalHost | The name of the local host through which connections are initiated or accepted. |
LocalPort | The port in the local host where the class binds. |
MaxLineLength | The maximum amount of data to accumulate when no EOL is found. |
MaxTransferRate | The transfer rate limit in bytes per second. |
ProxyExceptionsList | A semicolon separated list of hosts and IPs to bypass when using a proxy. |
TCPKeepAlive | Determines whether or not the keep alive socket option is enabled. |
TcpNoDelay | Whether or not to delay when sending packets. |
UseIPv6 | Whether to use IPv6. |
LogSSLPackets | Controls whether SSL packets are logged when using the internal security API. |
OpenSSLCADir | The path to a directory containing CA certificates. |
OpenSSLCAFile | Name of the file containing the list of CA's trusted by your application. |
OpenSSLCipherList | A string that controls the ciphers to be used by SSL. |
OpenSSLPrngSeedData | The data to seed the pseudo random number generator (PRNG). |
ReuseSSLSession | Determines if the SSL session is reused. |
SSLCACertFilePaths | The paths to CA certificate files on Unix/Linux. |
SSLCACerts | A newline separated list of CA certificate to be included when performing an SSL handshake. |
SSLCheckCRL | Whether to check the Certificate Revocation List for the server certificate. |
SSLCheckOCSP | Whether to use OCSP to check the status of the server certificate. |
SSLCipherStrength | The minimum cipher strength used for bulk encryption. |
SSLClientCACerts | A newline separated list of CA certificates to use during SSL client certificate validation. |
SSLEnabledCipherSuites | The cipher suite to be used in an SSL negotiation. |
SSLEnabledProtocols | Used to enable/disable the supported security protocols. |
SSLEnableRenegotiation | Whether the renegotiation_info SSL extension is supported. |
SSLIncludeCertChain | Whether the entire certificate chain is included in the SSLServerAuthentication event. |
SSLKeyLogFile | The location of a file where per-session secrets are written for debugging purposes. |
SSLNegotiatedCipher | Returns the negotiated cipher suite. |
SSLNegotiatedCipherStrength | Returns the negotiated cipher suite strength. |
SSLNegotiatedCipherSuite | Returns the negotiated cipher suite. |
SSLNegotiatedKeyExchange | Returns the negotiated key exchange algorithm. |
SSLNegotiatedKeyExchangeStrength | Returns the negotiated key exchange algorithm strength. |
SSLNegotiatedVersion | Returns the negotiated protocol version. |
SSLSecurityFlags | Flags that control certificate verification. |
SSLServerCACerts | A newline separated list of CA certificates to use during SSL server certificate validation. |
TLS12SignatureAlgorithms | Defines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal. |
TLS12SupportedGroups | The supported groups for ECC. |
TLS13KeyShareGroups | The groups for which to pregenerate key shares. |
TLS13SignatureAlgorithms | The allowed certificate signature algorithms. |
TLS13SupportedGroups | The supported groups for (EC)DHE key exchange. |
BuildInfo | Information about the product's build. |
CodePage | The system code page used for Unicode to Multibyte translations. |
LicenseInfo | Information about the current license. |
MaskSensitiveData | Whether sensitive data is masked in log messages. |
ProcessIdleEvents | Whether the class uses its internal event loop to process events when the main thread is idle. |
SelectWaitMillis | The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process. |
UseInternalSecurityAPI | Whether 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:
- call_call_id
- call_conference_id
- call_duration
- call_last_status
- call_local_address
- call_local_port
- call_microphone
- call_mute_microphone
- call_mute_speaker
- call_outgoing
- call_playing
- call_recording
- call_remote_address
- call_remote_port
- call_remote_uri
- call_remote_user
- call_speaker
- call_started_at
- call_state
- call_user_input
- call_via
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:
- microphone_channels
- microphone_manufacturer_id
- microphone_name
- microphone_product_id
- microphone_support
- microphone_supported_formats
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:
Bitmask | Flag | Description | |
0x0001 | WAVECAPS_PITCH | Supports pitch control. | |
0x0002 | WAVECAPS_PLAYBACKRATE | Supports playback rate control. | |
0x0004 | WAVECAPS_VOLUME | Supports volume control. | |
0x0008 | WAVECAPS_LRVOLUME | Supports separate left and right volume control. | |
0x0010 | WAVECAPS_SYNC | The driver is synchronous and will block while playing a buffer. | |
0x0020 | WAVECAPS_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:
Bitmask | Format | Description | |
0x00000001 | WAVE_FORMAT_1M08 | 11.025 kHz, mono, 8-bit | |
0x00000002 | WAVE_FORMAT_1S08 | 11.025 kHz, stereo, 8-bit | |
0x00000004 | WAVE_FORMAT_1M16 | 11.025 kHz, mono, 16-bit | |
0x00000008 | WAVE_FORMAT_1S16 | 11.025 kHz, stereo, 16-bit | |
0x00000010 | WAVE_FORMAT_2M08 | 22.05 kHz, mono, 8-bit | |
0x00000020 | WAVE_FORMAT_2S08 | 22.05 kHz, stereo, 8-bit | |
0x00000040 | WAVE_FORMAT_2M16 | 22.05 kHz, mono, 16-bit | |
0x00000080 | WAVE_FORMAT_2S16 | 22.05 kHz, stereo, 16-bit | |
0x00000100 | WAVE_FORMAT_4M08 | 44.1 kHz, mono, 8-bit | |
0x00000200 | WAVE_FORMAT_4S08 | 44.1 kHz, stereo, 8-bit | |
0x00000400 | WAVE_FORMAT_4M16 | 44.1 kHz, mono, 16-bit | |
0x00000800 | WAVE_FORMAT_4S16 | 44.1 kHz, stereo, 16-bit | |
0x00001000 | WAVE_FORMAT_48M08 | 48 kHz, mono, 8-bit | |
0x00002000 | WAVE_FORMAT_48S08 | 48 kHz, stereo, 8-bit | |
0x00004000 | WAVE_FORMAT_48M16 | 48 kHz, mono, 16-bit | |
0x00008000 | WAVE_FORMAT_48S16 | 48 kHz, stereo, 16-bit | |
0x00010000 | WAVE_FORMAT_96M08 | 96 kHz, mono, 8-bit | |
0x00020000 | WAVE_FORMAT_96S08 | 96 kHz, stereo, 8-bit | |
0x00040000 | WAVE_FORMAT_96M16 | 96 kHz, mono, 16-bit | |
0x00080000 | WAVE_FORMAT_96S16 | 96 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:
- speaker_channels
- speaker_manufacturer_id
- speaker_name
- speaker_product_id
- speaker_support
- speaker_supported_formats
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:
Bitmask | Flag | Description | |
0x0001 | WAVECAPS_PITCH | Supports pitch control. | |
0x0002 | WAVECAPS_PLAYBACKRATE | Supports playback rate control. | |
0x0004 | WAVECAPS_VOLUME | Supports volume control. | |
0x0008 | WAVECAPS_LRVOLUME | Supports separate left and right volume control. | |
0x0010 | WAVECAPS_SYNC | The driver is synchronous and will block while playing a buffer. | |
0x0020 | WAVECAPS_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:
Bitmask | Format | Description | |
0x00000001 | WAVE_FORMAT_1M08 | 11.025 kHz, mono, 8-bit | |
0x00000002 | WAVE_FORMAT_1S08 | 11.025 kHz, stereo, 8-bit | |
0x00000004 | WAVE_FORMAT_1M16 | 11.025 kHz, mono, 16-bit | |
0x00000008 | WAVE_FORMAT_1S16 | 11.025 kHz, stereo, 16-bit | |
0x00000010 | WAVE_FORMAT_2M08 | 22.05 kHz, mono, 8-bit | |
0x00000020 | WAVE_FORMAT_2S08 | 22.05 kHz, stereo, 8-bit | |
0x00000040 | WAVE_FORMAT_2M16 | 22.05 kHz, mono, 16-bit | |
0x00000080 | WAVE_FORMAT_2S16 | 22.05 kHz, stereo, 16-bit | |
0x00000100 | WAVE_FORMAT_4M08 | 44.1 kHz, mono, 8-bit | |
0x00000200 | WAVE_FORMAT_4S08 | 44.1 kHz, stereo, 8-bit | |
0x00000400 | WAVE_FORMAT_4M16 | 44.1 kHz, mono, 16-bit | |
0x00000800 | WAVE_FORMAT_4S16 | 44.1 kHz, stereo, 16-bit | |
0x00001000 | WAVE_FORMAT_48M08 | 48 kHz, mono, 8-bit | |
0x00002000 | WAVE_FORMAT_48S08 | 48 kHz, stereo, 8-bit | |
0x00004000 | WAVE_FORMAT_48M16 | 48 kHz, mono, 16-bit | |
0x00008000 | WAVE_FORMAT_48S16 | 48 kHz, stereo, 16-bit | |
0x00010000 | WAVE_FORMAT_96M08 | 96 kHz, mono, 8-bit | |
0x00020000 | WAVE_FORMAT_96S08 | 96 kHz, stereo, 8-bit | |
0x00040000 | WAVE_FORMAT_96M16 | 96 kHz, mono, 16-bit | |
0x00080000 | WAVE_FORMAT_96S16 | 96 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:
MY | A certificate store holding personal certificates with their associated private keys. |
CA | Certifying authority certificates. |
ROOT | Root 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:
|
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:
0x80 | Digital Signature |
0x40 | Non-Repudiation |
0x20 | Key Encipherment |
0x10 | Data Encipherment |
0x08 | Key Agreement |
0x04 | Certificate Signing |
0x02 | CRL Signing |
0x01 | Encipher 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:
Field | Meaning |
CN | Common Name. This is commonly a hostname like www.server.com. |
O | Organization |
OU | Organizational Unit |
L | Locality |
S | State |
C | Country |
E | Email 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:
MY | A certificate store holding personal certificates with their associated private keys. |
CA | Certifying authority certificates. |
ROOT | Root 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:
|
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:
0x80 | Digital Signature |
0x40 | Non-Repudiation |
0x20 | Key Encipherment |
0x10 | Data Encipherment |
0x08 | Key Agreement |
0x04 | Certificate Signing |
0x02 | CRL Signing |
0x01 | Encipher 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:
Field | Meaning |
CN | Common Name. This is commonly a hostname like www.server.com. |
O | Organization |
OU | Organizational Unit |
L | Locality |
S | State |
C | Country |
E | Email 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:
- The outgoing call has not been redirected. In this case, CallId is equal to OriginalCallId, and the value returned by dial is correct.
- 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.
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. |
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
By default, this value is empty, and the user property will be used within the mentioned headers.
8,0,3
The following integers correspond to these supported codecs:
0 | PCMU (G711MU) |
3 | GSM |
8 | PCMA (G711A) |
Component.Config("DeclineStatus=600 Busy Everywhere")
When using dial with the Wait parameter as false, the timeout will be reported within on_dial_completed.
Note: It is recommended to enable this configuration only if sip_transport_protocol is set to TCP or TLS.
1 | Inband (Default) |
2 | RFC 2833 |
3 | Info (SIP Info) |
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. |
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));
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.
UDP Config Settings
The default value for this setting is False.
Note: This configuration setting is available only in Windows.
The default value is False.
Note: This configuration setting is available only in Windows.
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).
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.
Note: This configuration setting uses the qWAVE API and is available only on Windows 7, Windows Server 2008 R2, and later.
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.
The default value for this setting is False.
Note: This configuration setting is available only in Windows and requires that the winpcap library be installed (or npcap with winpcap compatibility).
Note: This configuration setting is available only in Windows and requires that the winpcap library be installed (or npcap with winpcap compatibility).
The default value for this setting is False.
Socket Config Settings
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.
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.
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.
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.
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.
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
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.
Note: This setting is provided for use by classs that do not directly expose Firewall properties.
Note: This configuration setting is provided for use by classs that do not directly expose Firewall properties.
0 | No firewall (default setting). |
1 | Connect through a tunneling proxy. FirewallPort is set to 80. |
2 | Connect through a SOCKS4 Proxy. FirewallPort is set to 1080. |
3 | Connect through a SOCKS5 Proxy. FirewallPort is set to 1080. |
10 | Connect 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.
Note: This setting is provided for use by classs that do not directly expose Firewall properties.
Note: This value is not applicable in macOS.
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.
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).
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.
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.
www.google.com;www.nsoftware.com
Note: This value is not applicable in Java.
By default, this configuration setting is set to False.
0 | IPv4 only |
1 | IPv6 only |
2 | IPv6 with IPv4 fallback |
SSL Config Settings
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.
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.
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.
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".
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.
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.
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
-----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-----
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.
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.
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.
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-----
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
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.
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.3 | 12288 (Hex 3000) |
TLS1.2 | 3072 (Hex C00) (Default - Client and Server) |
TLS1.1 | 768 (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.
This configuration setting is applicable only when ssl_provider is set to Internal.
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.
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.
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]");
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]");
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]");
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]");
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]");
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]");
0x00000001 | Ignore time validity status of certificate. |
0x00000002 | Ignore time validity status of CTL. |
0x00000004 | Ignore non-nested certificate times. |
0x00000010 | Allow unknown certificate authority. |
0x00000020 | Ignore wrong certificate usage. |
0x00000100 | Ignore unknown certificate revocation status. |
0x00000200 | Ignore unknown CTL signer revocation status. |
0x00000400 | Ignore unknown certificate authority revocation status. |
0x00000800 | Ignore unknown root revocation status. |
0x00008000 | Allow test root certificate. |
0x00004000 | Trust test root certificate. |
0x80000000 | Ignore non-matching CN (certificate CN non-matching server name). |
This functionality is currently not available when the provider is OpenSSL.
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-----
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.
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)
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"
- "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 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
The following is a list of valid code page identifiers:
Identifier | Name |
037 | IBM EBCDIC - U.S./Canada |
437 | OEM - United States |
500 | IBM EBCDIC - International |
708 | Arabic - ASMO 708 |
709 | Arabic - ASMO 449+, BCON V4 |
710 | Arabic - Transparent Arabic |
720 | Arabic - Transparent ASMO |
737 | OEM - Greek (formerly 437G) |
775 | OEM - Baltic |
850 | OEM - Multilingual Latin I |
852 | OEM - Latin II |
855 | OEM - Cyrillic (primarily Russian) |
857 | OEM - Turkish |
858 | OEM - Multilingual Latin I + Euro symbol |
860 | OEM - Portuguese |
861 | OEM - Icelandic |
862 | OEM - Hebrew |
863 | OEM - Canadian-French |
864 | OEM - Arabic |
865 | OEM - Nordic |
866 | OEM - Russian |
869 | OEM - Modern Greek |
870 | IBM EBCDIC - Multilingual/ROECE (Latin-2) |
874 | ANSI/OEM - Thai (same as 28605, ISO 8859-15) |
875 | IBM EBCDIC - Modern Greek |
932 | ANSI/OEM - Japanese, Shift-JIS |
936 | ANSI/OEM - Simplified Chinese (PRC, Singapore) |
949 | ANSI/OEM - Korean (Unified Hangul Code) |
950 | ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC) |
1026 | IBM EBCDIC - Turkish (Latin-5) |
1047 | IBM EBCDIC - Latin 1/Open System |
1140 | IBM EBCDIC - U.S./Canada (037 + Euro symbol) |
1141 | IBM EBCDIC - Germany (20273 + Euro symbol) |
1142 | IBM EBCDIC - Denmark/Norway (20277 + Euro symbol) |
1143 | IBM EBCDIC - Finland/Sweden (20278 + Euro symbol) |
1144 | IBM EBCDIC - Italy (20280 + Euro symbol) |
1145 | IBM EBCDIC - Latin America/Spain (20284 + Euro symbol) |
1146 | IBM EBCDIC - United Kingdom (20285 + Euro symbol) |
1147 | IBM EBCDIC - France (20297 + Euro symbol) |
1148 | IBM EBCDIC - International (500 + Euro symbol) |
1149 | IBM EBCDIC - Icelandic (20871 + Euro symbol) |
1200 | Unicode UCS-2 Little-Endian (BMP of ISO 10646) |
1201 | Unicode UCS-2 Big-Endian |
1250 | ANSI - Central European |
1251 | ANSI - Cyrillic |
1252 | ANSI - Latin I |
1253 | ANSI - Greek |
1254 | ANSI - Turkish |
1255 | ANSI - Hebrew |
1256 | ANSI - Arabic |
1257 | ANSI - Baltic |
1258 | ANSI/OEM - Vietnamese |
1361 | Korean (Johab) |
10000 | MAC - Roman |
10001 | MAC - Japanese |
10002 | MAC - Traditional Chinese (Big5) |
10003 | MAC - Korean |
10004 | MAC - Arabic |
10005 | MAC - Hebrew |
10006 | MAC - Greek I |
10007 | MAC - Cyrillic |
10008 | MAC - Simplified Chinese (GB 2312) |
10010 | MAC - Romania |
10017 | MAC - Ukraine |
10021 | MAC - Thai |
10029 | MAC - Latin II |
10079 | MAC - Icelandic |
10081 | MAC - Turkish |
10082 | MAC - Croatia |
12000 | Unicode UCS-4 Little-Endian |
12001 | Unicode UCS-4 Big-Endian |
20000 | CNS - Taiwan |
20001 | TCA - Taiwan |
20002 | Eten - Taiwan |
20003 | IBM5550 - Taiwan |
20004 | TeleText - Taiwan |
20005 | Wang - Taiwan |
20105 | IA5 IRV International Alphabet No. 5 (7-bit) |
20106 | IA5 German (7-bit) |
20107 | IA5 Swedish (7-bit) |
20108 | IA5 Norwegian (7-bit) |
20127 | US-ASCII (7-bit) |
20261 | T.61 |
20269 | ISO 6937 Non-Spacing Accent |
20273 | IBM EBCDIC - Germany |
20277 | IBM EBCDIC - Denmark/Norway |
20278 | IBM EBCDIC - Finland/Sweden |
20280 | IBM EBCDIC - Italy |
20284 | IBM EBCDIC - Latin America/Spain |
20285 | IBM EBCDIC - United Kingdom |
20290 | IBM EBCDIC - Japanese Katakana Extended |
20297 | IBM EBCDIC - France |
20420 | IBM EBCDIC - Arabic |
20423 | IBM EBCDIC - Greek |
20424 | IBM EBCDIC - Hebrew |
20833 | IBM EBCDIC - Korean Extended |
20838 | IBM EBCDIC - Thai |
20866 | Russian - KOI8-R |
20871 | IBM EBCDIC - Icelandic |
20880 | IBM EBCDIC - Cyrillic (Russian) |
20905 | IBM EBCDIC - Turkish |
20924 | IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol) |
20932 | JIS X 0208-1990 & 0121-1990 |
20936 | Simplified Chinese (GB2312) |
21025 | IBM EBCDIC - Cyrillic (Serbian, Bulgarian) |
21027 | Extended Alpha Lowercase |
21866 | Ukrainian (KOI8-U) |
28591 | ISO 8859-1 Latin I |
28592 | ISO 8859-2 Central Europe |
28593 | ISO 8859-3 Latin 3 |
28594 | ISO 8859-4 Baltic |
28595 | ISO 8859-5 Cyrillic |
28596 | ISO 8859-6 Arabic |
28597 | ISO 8859-7 Greek |
28598 | ISO 8859-8 Hebrew |
28599 | ISO 8859-9 Latin 5 |
28605 | ISO 8859-15 Latin 9 |
29001 | Europa 3 |
38598 | ISO 8859-8 Hebrew |
50220 | ISO 2022 Japanese with no halfwidth Katakana |
50221 | ISO 2022 Japanese with halfwidth Katakana |
50222 | ISO 2022 Japanese JIS X 0201-1989 |
50225 | ISO 2022 Korean |
50227 | ISO 2022 Simplified Chinese |
50229 | ISO 2022 Traditional Chinese |
50930 | Japanese (Katakana) Extended |
50931 | US/Canada and Japanese |
50933 | Korean Extended and Korean |
50935 | Simplified Chinese Extended and Simplified Chinese |
50936 | Simplified Chinese |
50937 | US/Canada and Traditional Chinese |
50939 | Japanese (Latin) Extended and Japanese |
51932 | EUC - Japanese |
51936 | EUC - Simplified Chinese |
51949 | EUC - Korean |
51950 | EUC - Traditional Chinese |
52936 | HZ-GB2312 Simplified Chinese |
54936 | Windows XP: GB18030 Simplified Chinese (4 Byte) |
57002 | ISCII Devanagari |
57003 | ISCII Bengali |
57004 | ISCII Tamil |
57005 | ISCII Telugu |
57006 | ISCII Assamese |
57007 | ISCII Oriya |
57008 | ISCII Kannada |
57009 | ISCII Malayalam |
57010 | ISCII Gujarati |
57011 | ISCII Punjabi |
65000 | Unicode UTF-7 |
65001 | Unicode UTF-8 |
Identifier | Name |
1 | ASCII |
2 | NEXTSTEP |
3 | JapaneseEUC |
4 | UTF8 |
5 | ISOLatin1 |
6 | Symbol |
7 | NonLossyASCII |
8 | ShiftJIS |
9 | ISOLatin2 |
10 | Unicode |
11 | WindowsCP1251 |
12 | WindowsCP1252 |
13 | WindowsCP1253 |
14 | WindowsCP1254 |
15 | WindowsCP1250 |
21 | ISO2022JP |
30 | MacOSRoman |
10 | UTF16String |
0x90000100 | UTF16BigEndian |
0x94000100 | UTF16LittleEndian |
0x8c000100 | UTF32String |
0x98000100 | UTF32BigEndian |
0x9c000100 | UTF32LittleEndian |
65536 | Proprietary |
- 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.
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.
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). |