IVR Component

Properties Methods Events Config Settings Errors

The IVR component can be used to implement an Interactive Voice Response (IVR) menu.

Syntax

TipvIVR

Remarks

The IVR component can be used to implement an IVR menu utilizing modern Voice over Internet Protocol (VoIP) technology. This softphone offers a comprehensive set of features, including the ability to handle incoming calls, detect touch-tone inputs from the caller, and perform other common Voice over Internet Protocol (VoIP) operations. With this, you have a level of flexibility and control when it comes to designing and customizing menu options.

Registration

To begin, the first step is activating, or registering, the component. 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 component has successfully activated/registered, the Activated event will fire and Active will be set to true. The component 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 component 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, NegotiatedRegistrationInterval will reflect the negotiated lifetime. Afterwards, the component will attempt to refresh the registration every NegotiatedRegistrationInterval seconds.

Clients may wish to refresh the registration 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 NegotiatedRegistrationInterval. For example, to refresh the registration 5 seconds prior to it's expiration, the following can be performed after activation:

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

To prevent the registration from expiring, the component will refresh the registration within DoEvents according to the value of NegotiatedRegistrationInterval, or RefreshInterval if specified. To ensure this occurs, we recommend calling DoEvents 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 DoEvents should already be called in a loop to provide efficient message processing.

Security

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

Enable SIPS

To enable SIPS (Secure SIP, or SIP over SSL/TLS), the SIPTransportProtocol property must be set to 2 (TLS). The Port property will typically need to be set to 5061 (this may vary). Additionally, the SSLServerAuthentication event may be handled, allowing users to check the server identity and other security attributes related to server authentication. Once this is complete, the component 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 SSLStatus event with the prefix [SIP TLS].

Enable SRTP

While the above process secures SIP signaling, it does not secure RTP (audio) communication. The RTPSecurityMode 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 RTPSecurityMode 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 SIPTransportProtocol 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.

Handle Incoming Calls

After successful activation, incoming calls will be detected, and IncomingCall will fire for each call. Within this event, Answer or Decline can be used to handle these calls. For example:

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

Automated Responses

Throughout the menu, there are various ways to prompt a caller. For example, you may want to play an initial message to an answered call. Once a call has been answered, the CallReady event will fire, where you can use either PlayText, PlayFile, or PlayBytes to do so. For example:

ivr1.OnCallReady += (o, e) => { ivr1.PlayText(e.CallId, "Please press 1 to be transferred to sales. Press 2 to be transferred to support. Press 3 to hear the options again."); };

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). Note that these methods are non-blocking. The component can play audio to multiple calls at once.

Once the audio has finished playing to a particular call, the Played event will fire, with the CallId as a parameter. Please see PlayBytes and Played for more information on expected behavior when playing bytes.

Handle User Input

A main focus of an IVR menu revolves around handling user input. The component keeps track of the touch-tone inputs of a caller in the call's "UserInput" field. Additionally, the Digit event will fire whenever user input is detected. The event will contain parameters for the Digit pressed, and the associated CallId. The component can detect digits 0-9, *, and # tones. Based on current and previous inputs, you can implement various menu options, from transferring calls to certain extensions, checking a user's account status, placing user's on hold, etc. For example:

ivr1.OnDigit += (o, e) => { if (e.Digit.Equals("1")) { ivr1.Transfer(e.CallId, "Sales Number"); } else if (e.Digit.Equals("2")) { ivr1.Transfer(e.CallId, "Support Number"); } else if (e.Digit.Equals("3")) { ivr1.PlayText(e.CallId, "Please press 1 to be transferred to sales. Press 2 to be transferred to support. Press 3 to hear the options again."); } else { // Unhandled input } };

Call Termination

Ongoing calls are terminated by passing the appropriate CallId to Hangup. All ongoing calls can be terminated with HangupAll. When a call has been terminated (by either party), CallTerminated will fire.

Property List

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


Active	The current activation status of the component.
Calls	A collection of calls.
LocalHost	The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
LocalPort	This property includes the User Datagram Protocol (UDP) port in the local host where UDP binds.
Password	The password that is used when connecting to the SIP Server.
Port	The port on the SIP server the component is connecting to.
RTPSecurityMode	Specifies the security mode that will be used when transmitting RTP.
Server	The address of the SIP Server.
SIPTransportProtocol	Specifies the transport protocol the component will use for SIP signaling.
SSLAcceptServerCert	Instructs the component to unconditionally accept the server certificate that matches the supplied certificate.
SSLCert	The certificate to be used during SSL negotiation.
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 component with short descriptions. Click on the links for further details.


Activate	Activates the component.
Answer	Answers an incoming phone call.
Config	Sets or retrieves a configuration setting.
Deactivate	Deactivates the component.
Decline	Declines an incoming phone call.
Dial	Used to make a call.
DoEvents	This method processes events from the internal message queue.
Hangup	Used to hang up a specific call.
HangupAll	Used to hang up all calls.
Hold	Places a call on hold.
Ping	Used to ping the server.
PlayBytes	This method is used to play bytes to a call.
PlayFile	Plays audio from a WAV file to a call.
PlayText	Plays audio from a string to a call using Text-to-Speech.
Reset	This method will reset the component.
StartRecording	Used to start recording the audio of a call.
StopPlaying	Stops audio from playing to a call.
StopRecording	Stops recording the audio of a call.
Transfer	Transfers a call.
Unhold	Takes a call off hold.

Event List

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


Activated	This event is fired immediately after the component is activated.
CallReady	This event is fired after a call has been answered, declined, or ignored.
CallStateChanged	This event is fired after a call's state has changed.
CallTerminated	This event is fired after a call has been terminated.
Deactivated	This event is fired immediately after the component is deactivated.
DialCompleted	This event is fired after the dial process has finished.
Digit	This event fires every time a digit is pressed using the keypad.
Error	Fired when information is available about errors during data delivery.
IncomingCall	This event is fired when an incoming call is received.
Log	This event is fired once for each log message.
OutgoingCall	This event is fired when an outgoing call has been made.
Played	This event is fired after the component finishes playing available audio.
Record	This event is fired when recorded audio data is available.
Silence	This event is fired when the component detects silence from incoming audio streams.
SSLServerAuthentication	Fired after the server presents its certificate to the client.
SSLStatus	Fired when secure connection progress messages are available.

Config Settings

The following is a list of config settings for the component 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 component 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 component will log encoded audio data.
LogLevel	The level of detail that is logged.
LogRTPPackets	Whether the component will log RTP packets.
NegotiatedRegistrationInterval	Specifies the negotiated lifetime of the current registration after successful activation.
RecordType	The type of recording the component 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	Used to specify the desired lifetime of the registration to the server prior to activation.
RingtoneFile	Specifies location of a WAV file to play when receiving an incoming call.
SilenceInterval	Specifies the interval the component uses to detect periods of silence.
STUNPort	The port of the STUN server.
STUNServer	The address of the STUN Server.
UnregisterOnActivate	Specifies whether the component will unregister from the SIP Server before registration.
UserAgent	Information about the user agent (client).
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 component 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 component 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 component 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;.
FirewallTunnelAuthScheme	This configuration setting specifies the authentication mechanism to use when authenticating to a tunneling proxy.
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 component 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.
LogSSLPackets	Controls whether SSL packets are logged when using the internal security API.
OpenSSLCADir	The path to a directory containing CA certificates.
OpenSSLCADir	The path to a directory containing CA certificates.
OpenSSLCAFile	Name of the file containing the list of CA's trusted by your application.
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.
OpenSSLCipherList	A string that controls the ciphers to be used by SSL.
OpenSSLPrngSeedData	The data to seed the pseudo random number generator (PRNG).
OpenSSLPrngSeedData	The data to seed the pseudo random number generator (PRNG).
ReuseSSLSession	Determines if the SSL session is reused.
ReuseSSLSession	Determines if the SSL session is reused.
SSLCACertFilePaths	The paths to CA certificate files on Unix/Linux.
SSLCACertFilePaths	The paths to CA certificate files on Unix/Linux.
SSLCACerts	A newline separated list of CA certificates to be included when performing an SSL handshake.
SSLCACerts	A newline separated list of CA certificates to be included when performing an SSL handshake.
SSLCheckCRL	Whether to check the Certificate Revocation List for the server certificate.
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.
SSLCheckOCSP	Whether to use OCSP to check the status of the server certificate.
SSLCipherStrength	The minimum cipher strength used for bulk encryption.
SSLCipherStrength	The minimum cipher strength used for bulk encryption.
SSLClientCACerts	A newline separated list of CA certificates to use during SSL client certificate validation.
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.
SSLEnabledCipherSuites	The cipher suite to be used in an SSL negotiation.
SSLEnabledProtocols	Used to enable/disable the supported security protocols.
SSLEnabledProtocols	Used to enable/disable the supported security protocols.
SSLEnableRenegotiation	Whether the renegotiation_info SSL extension is supported.
SSLEnableRenegotiation	Whether the renegotiation_info SSL extension is supported.
SSLIncludeCertChain	Whether the entire certificate chain is included in the SSLServerAuthentication event.
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.
SSLKeyLogFile	The location of a file where per-session secrets are written for debugging purposes.
SSLNegotiatedCipher	Returns the negotiated cipher suite.
SSLNegotiatedCipher	Returns the negotiated cipher suite.
SSLNegotiatedCipherStrength	Returns the negotiated cipher suite strength.
SSLNegotiatedCipherStrength	Returns the negotiated cipher suite strength.
SSLNegotiatedCipherSuite	Returns the negotiated cipher suite.
SSLNegotiatedCipherSuite	Returns the negotiated cipher suite.
SSLNegotiatedKeyExchange	Returns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchange	Returns the negotiated key exchange algorithm.
SSLNegotiatedKeyExchangeStrength	Returns the negotiated key exchange algorithm strength.
SSLNegotiatedKeyExchangeStrength	Returns the negotiated key exchange algorithm strength.
SSLNegotiatedVersion	Returns the negotiated protocol version.
SSLNegotiatedVersion	Returns the negotiated protocol version.
SSLSecurityFlags	Flags that control certificate verification.
SSLSecurityFlags	Flags that control certificate verification.
SSLServerCACerts	A newline separated list of CA certificates to use during SSL server certificate validation.
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.
TLS12SignatureAlgorithms	Defines the allowed TLS 1.2 signature algorithms when SSLProvider is set to Internal.
TLS12SupportedGroups	The supported groups for ECC.
TLS12SupportedGroups	The supported groups for ECC.
TLS13KeyShareGroups	The groups for which to pregenerate key shares.
TLS13KeyShareGroups	The groups for which to pregenerate key shares.
TLS13SignatureAlgorithms	The allowed certificate signature algorithms.
TLS13SignatureAlgorithms	The allowed certificate signature algorithms.
TLS13SupportedGroups	The supported groups for (EC)DHE key exchange.
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 component uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the component will wait when DoEvents is called if there are no events to process.
UseFIPSCompliantAPI	Tells the component whether or not to use FIPS certified APIs.
UseInternalSecurityAPI	Whether or not to use the system security libraries or an internal implementation.

Active Property (IVR Component)

The current activation status of the component.

Syntax

property Active: Boolean read get_Active;

Default Value

false

Remarks

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

The component can be activated via Activate and deactivated through Deactivate.

This property is read-only and not available at design time.

Calls Property (IVR Component)

A collection of calls.

Syntax

property Calls: TipvCallList read get_Calls;

Remarks

This collection holds data for each incoming and outgoing Call recognized by the component.

This property is read-only and not available at design time.

Please refer to the Call type for a complete list of fields.

LocalHost Property (IVR Component)

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

Syntax

property LocalHost: String read get_LocalHost write set_LocalHost;

Default Value

Remarks

This 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 component initiate connections (or accept in the case of server components) 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 component is connected, the LocalHost 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: LocalHost is not persistent. You must always set it in code, and never in the property window.

LocalPort Property (IVR Component)

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

Syntax

property LocalPort: Integer read get_LocalPort write set_LocalPort;

Default Value

Remarks

The LocalPort property must be set before UDP is activated (Active is set to True). This instructs the component 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 LocalPort property after the connection is established.

LocalPort cannot be changed once the component is Active. Any attempt to set the LocalPort property when the component is Active will generate an error.

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

Password Property (IVR Component)

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

Syntax

property Password: String read get_Password write 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 component via Activate.

This property is not available at design time.

Port Property (IVR Component)

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

Syntax

property Port: Integer read get_Port write set_Port;

Default Value

5060

Remarks

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

RTPSecurityMode Property (IVR Component)

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

Syntax

property RTPSecurityMode: TipvTRTPSecurityModes read get_RTPSecurityMode write set_RTPSecurityMode;

TipvTRTPSecurityModes = (
  etNone,
  etSDES,
  etDTLS
);

Default Value

etNone

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 SIPTransportProtocol is set to TLS when enabling SRTP.

Server Property (IVR Component)

The address of the SIP Server.

Syntax

property Server: String read get_Server write set_Server;

Default Value

Remarks

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

SIPTransportProtocol Property (IVR Component)

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

Syntax

property SIPTransportProtocol: TipvTSIPTransportProtocols read get_SIPTransportProtocol write set_SIPTransportProtocol;

TipvTSIPTransportProtocols = (
  tpUDP,
  tpTCP,
  tpTLS
);

Default Value

tpUDP

Remarks

This property specifies which transport protocol (UDP, TCP, TLS) the component will use for SIP signaling and can be used to enable SIPS (Secure SIP). Note it is important to set the SIPTransportProtocol 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.

SSLAcceptServerCert Property (IVR Component)

Instructs the component to unconditionally accept the server certificate that matches the supplied certificate.

Syntax

property SSLAcceptServerCert: TipvCertificate read get_SSLAcceptServerCert write set_SSLAcceptServerCert;

Remarks

If it finds any issues with the certificate presented by the server, the component will normally terminate the connection with an error.

You may override this behavior by supplying a value for SSLAcceptServerCert. If the certificate supplied in SSLAcceptServerCert is the same as the certificate presented by the server, then the server certificate is accepted unconditionally, and the connection will continue normally.

Please note that this functionality is provided only for cases where you otherwise know that you are communicating with the right server. If used improperly, this property may create a security breach. Use it at your own risk.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

SSLCert Property (IVR Component)

The certificate to be used during SSL negotiation.

Syntax

property SSLCert: TipvCertificate read get_SSLCert write set_SSLCert;

Remarks

The digital certificate that the component will use during SSL negotiation. Set this property to a valid certificate before starting SSL negotiation. To set a certificate, you may set the Encoded field to the encoded certificate. To select a certificate, use the store and subject fields.

This property is not available at design time.

Please refer to the Certificate type for a complete list of fields.

User Property (IVR Component)

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

Syntax

property User: String read get_User write 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 component via Activate.

This property is not available at design time.

Activate Method (IVR Component)

Activates the component.

Syntax

procedure Activate();

Remarks

This method is used to activate the component 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 Activated event will fire.

Answer Method (IVR Component)

Answers an incoming phone call.

Syntax

procedure Answer(CallId: String);

Remarks

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

Config Method (IVR Component)

Sets or retrieves a configuration setting.

Syntax

function Config(ConfigurationString: String): String;

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the component, 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 (IVR Component)

Deactivates the component.

Syntax

procedure Deactivate();

Remarks

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

Decline Method (IVR Component)

Declines an incoming phone call.

Syntax

procedure Decline(CallId: String);

Remarks

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

Dial Method (IVR Component)

Used to make a call.

Syntax

function Dial(Number: String; CallerNumber: String; Wait: Boolean): String;

Remarks

This method is used to make a call to a particular user, given by Number. This method should only be called after the component has been successfully activated via Activate. Initially, the OutgoingCall event will fire after calling this method. DialCompleted may fire when the dial process is complete. If successful, CallReady will fire after the outgoing call has been answered, declined, or ignored. If the call is declined or ignored, the component 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 component should connect synchronously or asynchronously to the call. If True, the component will connect synchronously, and won't return until the call has been answered, declined, or ignored. If False, the component will connect asynchronously. The call's status can be checked through various events, such as OutgoingCall, CallReady, and CallStateChanged, or found in the call's State field. Exceptions throughout the call process will be reported in DialCompleted, 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 component must change this field. Both the updated and original CallId will be present within the DialCompleted event. Any references to the original CallId must be updated accordingly. Please see DialCompleted 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"); }

DoEvents Method (IVR Component)

This method processes events from the internal message queue.

Syntax

procedure DoEvents();

Remarks

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

Hangup Method (IVR Component)

Used to hang up a specific call.

Syntax

procedure Hangup(CallId: String);

Remarks

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

HangupAll Method (IVR Component)

Used to hang up all calls.

Syntax

procedure HangupAll();

Remarks

This method is used to terminate all calls currently in the Calls collection. CallTerminated will fire for each successfully terminated call.

Hold Method (IVR Component)

Places a call on hold.

Syntax

procedure Hold(CallId: String);

Remarks

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

Ping Method (IVR Component)

Used to ping the server.

Syntax

procedure Ping(Timeout: Integer);

Remarks

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

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

PlayBytes Method (IVR Component)

This method is used to play bytes to a call.

Syntax

procedure PlayBytes(CallId: String; BytesToPlay: TBytes; LastBlock: Boolean);

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 Played event will fire.

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

If LastBlock is false, this indicates that the component should expect more calls to PlayBytes. Once all bytes have played and the buffer is empty, Played will fire as expected, and will continue firing until the LastBlock parameter is set to true. Within Played, the user can provide further bytes to PlayBytes. Please see below for detailed examples on how to use this method with 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 }

PlayFile Method (IVR Component)

Plays audio from a WAV file to a call.

Syntax

procedure PlayFile(CallId: String; WavFile: String);

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 CallReady 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 component can handle playing audio to concurrent calls. This method is non-blocking and will return immediately. The Played event will fire when the audio for the specified call has finished playing. Consecutive uses of PlayText or PlayFile can prevent prior audio transmissions from being completed. In the below example, Played will only fire for the second call to PlayText:

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.

PlayText Method (IVR Component)

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

Syntax

procedure PlayText(CallId: String; Text: String);

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 CallReady has fired.

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

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 (IVR Component)

This method will reset the component.

Syntax

procedure Reset();

Remarks

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

StartRecording Method (IVR Component)

Used to start recording the audio of a call.

Syntax

procedure StartRecording(CallId: String; FileName: String);

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 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 StopRecording. 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()); };

StopPlaying Method (IVR Component)

Stops audio from playing to a call.

Syntax

procedure StopPlaying(CallId: String);

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 SetMicrophone, however, will stop audio transmitting from usage of PlayText, PlayFile, and PlayBytes.

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

StopRecording Method (IVR Component)

Stops recording the audio of a call.

Syntax

procedure StopRecording(CallId: String);

Remarks

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

Transfer Method (IVR Component)

Transfers a call.

Syntax

procedure Transfer(CallId: String; Number: String);

Remarks

This method is used to transfer a call, specified by CallId, to the phone number given by Number. The component 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 component 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.

Unhold Method (IVR Component)

Takes a call off hold.

Syntax

procedure Unhold(CallId: String);

Remarks

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

Activated Event (IVR Component)

This event is fired immediately after the component is activated.

Syntax

type TActivatedEvent = procedure (
  Sender: TObject
) of Object;

property OnActivated: TActivatedEvent read FOnActivated write FOnActivated;

Remarks

The Activated event will fire after the component has successfully registered with the SIP Server via Activate.

CallReady Event (IVR Component)

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

Syntax

type TCallReadyEvent = procedure (
  Sender: TObject;
  const CallId: String
) of Object;

property OnCallReady: TCallReadyEvent read FOnCallReady write FOnCallReady;

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 component will be sent to voicemail. Hangup can be used to end the call in all scenarios.

Note that this event will fire after OutgoingCall and DialCompleted, assuming Dial was successful.

The CallId parameter is the unique Id of the call.

CallStateChanged Event (IVR Component)

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

Syntax

type TCallStateChangedEvent = procedure (
  Sender: TObject;
  const CallId: String;
  State: Integer
) of Object;

property OnCallStateChanged: TCallStateChangedEvent read FOnCallStateChanged write FOnCallStateChanged;

Remarks

The CallStateChanged 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.

CallTerminated Event (IVR Component)

This event is fired after a call has been terminated.

Syntax

type TCallTerminatedEvent = procedure (
  Sender: TObject;
  const CallId: String
) of Object;

property OnCallTerminated: TCallTerminatedEvent read FOnCallTerminated write FOnCallTerminated;

Remarks

The CallTerminated 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.

Deactivated Event (IVR Component)

This event is fired immediately after the component is deactivated.

Syntax

type TDeactivatedEvent = procedure (
  Sender: TObject
) of Object;

property OnDeactivated: TDeactivatedEvent read FOnDeactivated write FOnDeactivated;

Remarks

The Deactivated event will fire after the component has unregistered from the SIP Server via Deactivate.

DialCompleted Event (IVR Component)

This event is fired after the dial process has finished.

Syntax

type TDialCompletedEvent = procedure (
  Sender: TObject;
  const OriginalCallId: String;
  const CallId: String;
  const Caller: String;
  const Callee: String;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnDialCompleted: TDialCompletedEvent read FOnDialCompleted write FOnDialCompleted;

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 component 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.

The Caller parameter specifies the user that initially made the call. The Callee parameter specifies the final recipient of the call.

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

Digit Event (IVR Component)

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

Syntax

type TDigitEvent = procedure (
  Sender: TObject;
  const CallId: String;
  const Digit: String
) of Object;

property OnDigit: TDigitEvent read FOnDigit write FOnDigit;

Remarks

The 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 component's inputs via TypeDigit. Detectable inputs include: 0-9, *, #

The CallId parameter is the unique Id of the call.

Error Event (IVR Component)

Fired when information is available about errors during data delivery.

Syntax

type TErrorEvent = procedure (
  Sender: TObject;
  ErrorCode: Integer;
  const Description: String
) of Object;

property OnError: TErrorEvent read FOnError write FOnError;

Remarks

The Error event is fired in case of exceptional conditions during message processing. Normally the component raises an exception.

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.

IncomingCall Event (IVR Component)

This event is fired when an incoming call is received.

Syntax

type TIncomingCallEvent = procedure (
  Sender: TObject;
  const CallId: String;
  const RemoteUser: String;
  const RequestURI: String;
  const ToURI: String
) of Object;

property OnIncomingCall: TIncomingCallEvent read FOnIncomingCall write FOnIncomingCall;

Remarks

The IncomingCall 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.

Log Event (IVR Component)

This event is fired once for each log message.

Syntax

type TLogEvent = procedure (
  Sender: TObject;
  LogLevel: Integer;
  const Message: String;
  const LogType: String
) of Object;

property OnLog: TLogEvent read FOnLog write FOnLog;

Remarks

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

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


0 (None)	No messages are logged.
1 (Info - Default)	Informational events such as a call's status are logged.
2 (Verbose)	Detailed data such as SIP/SDP packet information is logged.
3 (Debug)	Debug data including all relevant sent and received audio bytes are logged.

Note: When LogLevel is set to 3 (Debug), we strongly advise against performing long-running operations inside of this event due to large amounts of sent and received audio bytes. For example, continuously updating an interface displaying the Log data will cause major performance issues in an application. It is recommended to set LogLevel to 3 only when writing Log data to a stream or file. There will be no performance issues in this case.

Message is the log message.

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

Info
Packet
RTP

OutgoingCall Event (IVR Component)

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

Syntax

type TOutgoingCallEvent = procedure (
  Sender: TObject;
  const CallId: String;
  const RemoteUser: String
) of Object;

property OnOutgoingCall: TOutgoingCallEvent read FOnOutgoingCall write FOnOutgoingCall;

Remarks

The OutgoingCall 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.

Played Event (IVR Component)

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

Syntax

type TPlayedEvent = procedure (
  Sender: TObject;
  const CallId: String;
  Completed: Boolean
) of Object;

property OnPlayed: TPlayedEvent read FOnPlayed write FOnPlayed;

Remarks

The Played event will fire after the component finishes playing available audio to a call. When using PlayText or PlayFile, Completed will always be true. However, this will not always be the case when using PlayBytes.

When playing audio via PlayBytes, this event will fire when the internal byte queue is empty. In the event that the internal byte queue is empty, and the component is still expecting calls to PlayBytes (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 component is no longer expecting calls to PlayBytes (i.e., lastBlock is true). Please see the method description for more details.

The CallId parameter is the unique Id of the call.

Record Event (IVR Component)

This event is fired when recorded audio data is available.

Syntax

type TRecordEvent = procedure (
  Sender: TObject;
  const CallId: String;
  const RecordedData: String;
  const RecordedDataB: TBytes
) of Object;

property OnRecord: TRecordEvent read FOnRecord write FOnRecord;

Remarks

This event is fired when a call's recorded data is available. This data is made available when either StopRecording is called or the call is terminated. Note that for this event to fire, StartRecording 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.

Silence Event (IVR Component)

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

Syntax

type TSilenceEvent = procedure (
  Sender: TObject;
  const CallId: String
) of Object;

property OnSilence: TSilenceEvent read FOnSilence write FOnSilence;

Remarks

The Silence event will fire every second the component 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.

SSLServerAuthentication Event (IVR Component)

Fired after the server presents its certificate to the client.

Syntax

type TSSLServerAuthenticationEvent = procedure (
  Sender: TObject;
  const CertEncoded: String;
  const CertEncodedB: TBytes;
  const CertSubject: String;
  const CertIssuer: String;
  const Status: String;
  var Accept: Boolean
) of Object;

property OnSSLServerAuthentication: TSSLServerAuthenticationEvent read FOnSSLServerAuthentication write FOnSSLServerAuthentication;

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.

SSLStatus Event (IVR Component)

Fired when secure connection progress messages are available.

Syntax

type TSSLStatusEvent = procedure (
  Sender: TObject;
  const Message: String
) of Object;

property OnSSLStatus: TSSLStatusEvent read FOnSSLStatus write FOnSSLStatus;

Remarks

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

Call Type

Contains the details of an active call.

Remarks

This type contains the details of an active call.

The following fields are available:

Fields

CallId
String (read-only)
Default Value: ""

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

ConferenceId
String (read-only)
Default Value: ""

A unique identifier for a conference call.

Duration
Integer (read-only)
Default Value: 0

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

LastStatus
Integer (read-only)
Default Value: 0

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

LocalAddress
String (read-only)
Default Value: ""

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

LocalPort
Integer (read-only)
Default Value: 0

The UDP port in the local host where UDP binds.

Microphone
String (read-only)
Default Value: ""

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

MuteMicrophone
Boolean
Default Value: False

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

MuteSpeaker
Boolean
Default Value: False

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

Outgoing
Boolean (read-only)
Default Value: False

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

Playing
Boolean (read-only)
Default Value: False

Indicates whether the current call is playing audio via PlayText or PlayFile, or PlayBytes. After audio transmission is complete, or stopped using StopPlaying, this flag will be false.

Recording
Boolean (read-only)
Default Value: False

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 StopRecording, this flag will be false.

RemoteAddress
String (read-only)
Default Value: ""

The address of the remote host we are communicating with.

RemotePort
Integer (read-only)
Default Value: 0

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

RemoteURI
String (read-only)
Default Value: ""

This field communicates who to call via SIP. This value contains the RemoteUser, RemoteAddress, and the RemotePort, and has the following format:

sip:user@host:port

RemoteUser
String (read-only)
Default Value: ""

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

Speaker
String (read-only)
Default Value: ""

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

StartedAt
Int64 (read-only)
Default Value: 0

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

State
TipvCallStates
Default Value: 0

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.

UserInput
String (read-only)
Default Value: ""

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

Via
String (read-only)
Default Value: ""

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.

Constructors

constructor Create();

Certificate Type

This is the digital certificate being used.

Remarks

This type describes the current digital certificate. The certificate may be a public or private key. The fields are used to identify or select certificates.

The following fields are available:

Fields

EffectiveDate
String (read-only)
Default Value: ""

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.

ExpirationDate
String (read-only)
Default Value: ""

The date on which 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.

ExtendedKeyUsage
String (read-only)
Default Value: ""

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

Fingerprint
String (read-only)
Default Value: ""

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

FingerprintSHA1
String (read-only)
Default Value: ""

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

FingerprintSHA256
String (read-only)
Default Value: ""

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

Issuer
String (read-only)
Default Value: ""

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

PrivateKey
String (read-only)
Default Value: ""

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

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

PrivateKeyAvailable
Boolean (read-only)
Default Value: False

Whether a PrivateKey is available for the selected certificate. If PrivateKeyAvailable is True, the certificate may be used for authentication purposes (e.g., server authentication).

PrivateKeyContainer
String (read-only)
Default Value: ""

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

PublicKey
String (read-only)
Default Value: ""

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

PublicKeyAlgorithm
String (read-only)
Default Value: ""

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.

PublicKeyLength
Integer (read-only)
Default Value: 0

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

SerialNumber
String (read-only)
Default Value: ""

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.

SignatureAlgorithm
String (read-only)
Default Value: ""

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.

Store
String
Default Value: "MY"

The name of the certificate store for the client certificate.

The StoreType property denotes the type of the certificate store specified by Store. If the store is password-protected, specify the password in StorePassword.

Store is used in conjunction with the Subject property to specify client certificates. If Store has a value, and Subject or Encoded is set, a search for a certificate is initiated. Please see the 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 cstPFXFile, this property must be set to the name of the file. When the type is cstPFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

StoreB
TBytes
Default Value: "MY"

The name of the certificate store for the client certificate.

The StoreType property denotes the type of the certificate store specified by Store. If the store is password-protected, specify the password in StorePassword.

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.

StorePassword
String
Default Value: ""

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

StoreType
TipvCertStoreTypes
Default Value: 0

The type of certificate store for this certificate.

The component supports both public and private keys in a variety of formats. When the cstAuto value is used, the component 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 component. The ListStoreCertificates method may be called after setting CertStoreType to `cstPKCS11`, CertStorePassword to the PIN, and CertStore to the full path of the PKCS#11 DLL. The certificate information returned in the CertList event's `CertEncoded` parameter may be saved for later use. When using a certificate, pass the previously saved security key information as the Store and set StorePassword to the PIN. Code Example. SSH Authentication with Security Key: `certmgr.CertStoreType = CertStoreTypes.cstPKCS11; certmgr.OnCertList += (s, e) => { secKeyBlob = e.CertEncoded; }; certmgr.CertStore = @"C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll"; certmgr.CertStorePassword = "123456"; //PIN certmgr.ListStoreCertificates(); sftp.SSHCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "123456", "*"); sftp.SSHUser = "test"; sftp.SSHLogon("myhost", 22);`
99 (cstAuto)	The store type is automatically detected from the input data. This setting may be used with both public and private keys and can detect any of the supported formats automatically.

SubjectAltNames
String (read-only)
Default Value: ""

Comma-separated lists of alternative subject names for the certificate.

ThumbprintMD5
String (read-only)
Default Value: ""

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.

ThumbprintSHA1
String (read-only)
Default Value: ""

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.

ThumbprintSHA256
String (read-only)
Default Value: ""

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.

Usage
String (read-only)
Default Value: ""

The text description of UsageFlags.

This value will be 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.

UsageFlags
Integer (read-only)
Default Value: 0

The flags that show intended use for the certificate. The value of UsageFlags 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 Usage property for a text representation of UsageFlags.

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

Version
String (read-only)
Default Value: ""

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

Subject
String
Default Value: ""

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.

Encoded
String
Default Value: ""

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

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

EncodedB
TBytes
Default Value: ""

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

Constructors

constructor Create();

Creates a instance whose properties can be set. This is useful for use with when generating new certificates.

constructor Create(valEncoded: TBytes);

Parses Encoded as an X.509 public key.

constructor Create(valStoreType: TipvCertStoreTypes; valStore: String; valStorePassword: String; valSubject: String);

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a file containing the certificate store. StorePassword is the password used to protect the store.

After the store has been successfully opened, the component will attempt to find the certificate identified by Subject . This can be either a complete or a substring match of the X.509 certificate's subject Distinguished Name (DN). The Subject parameter can also take an MD5, SHA-1, or SHA-256 thumbprint of the certificate to load in a "Thumbprint=value" format.

constructor Create(valStoreType: TipvCertStoreTypes; valStore: TBytes; valStorePassword: String; valSubject: String);

StoreType identifies the type of certificate store to use. See for descriptions of the different certificate stores. Store is a byte array containing the certificate data. StorePassword is the password used to protect the store.

Config Settings (IVR Component)

The component 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 component, access to these internal properties is provided through the Config method.

IPPhone Config Settings

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

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

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

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

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

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

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

8,0,3

The following integers correspond to these supported codecs:


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

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

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

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

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

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

When using Dial with the Wait parameter as false, the timeout will be reported within DialCompleted.

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

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

DisableRegistration: Can be used to disable SIP registration.

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

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

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

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

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

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


1	Inband (Default)
2	RFC 2833
3	Info (SIP Info)

EnableDynamicRecording: Specifies whether dynamic recording is enabled when recording a call.

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

LogEncodedAudioData: Whether the component will log encoded audio data.

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

LogLevel: The level of detail that is logged.

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


0 (None)	No messages are logged.
1 (Info - Default)	Informational events such as a call's status are logged.
2 (Verbose)	Detailed data such as SIP/SDP packet information is logged.
3 (Debug)	Debug data including all relevant sent and received audio bytes are logged.

Note: When LogLevel is set to 3 (Debug), we strongly advise against performing long-running operations inside of this event due to large amounts of sent and received audio bytes. For example, continuously updating an interface displaying the Log data will cause major performance issues in an application. It is recommended to set LogLevel to 3 only when writing Log data to a stream or file. There will be no performance issues in this case.

LogRTPPackets: Whether the component will log RTP packets.

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

NegotiatedRegistrationInterval: Specifies the negotiated lifetime of the current registration after successful activation.

After successful activation, this config specifies the lifetime (in seconds) of the current registration as determined by the server. If RefreshInterval is set, it should be less than or equal to the value returned by this config.

RecordType: The type of recording the component will use.

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

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

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

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

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

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

component.Config("RefreshInterval=120"); // proposed registration lifetime component.Activate(); int lifetime = component.Config("NegotiatedRegistrationInterval"); // negotiated registration lifetime // Refresh the registration halfway through its lifetime. component.Config("RefreshInterval=" + (lifetime / 2));

RegistrationInterval: Used to specify the desired lifetime of the registration to the server prior to activation.

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

After successfully calling Activate, the NegotiatedRegistrationInterval config will contain the actual, negotiated lifetime of the registration.

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

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

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

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

STUNPort: The port of the STUN server.

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

STUNServer: The address of the STUN Server.

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

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

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

UserAgent: Information about the user agent (client).

This config specifies information about the user agent (client). The value specified here will be supplied in the SIP User-Agent header.

By default, this value is empty, and no User-Agent header will be sent. If set, the User-Agent header will be present in all outgoing requests.

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

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

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

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

UDP Config Settings

CaptureIPPacketInfo: Used to capture the packet information.

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

The default value for this setting is False.

Note: This configuration setting is available only in Windows.

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

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

The default value is False.

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

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

Note: This configuration setting is available only in Windows.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The default value for this setting is False.

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

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

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

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

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

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

UseConnection: Determines whether to use a connected socket.

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

The default value for this setting is False.

UseIPv6: Whether or not to use IPv6.

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

Socket Config Settings

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

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

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

Determines whether timeouts are inactivity timeouts or absolute timeouts.