4. Exported Functions

4.1.  uac_replace_from(display, uri)

Replaces the display name and URI in FROM header with the new values passed as parameters.

At least one of the two parameters should be set to non null value.

Function returns true only if the replacement operation was successfully completed.

Meaning of the parameters is as follows:

  • display - the new value for the FROM display name. If display is an empty string, the FROM display name will be removed from the FROM header.

  • uri - the new value for the FROM URI - it must be a valid SIP URI. If the uri is an empty string, the FROM URI will be left untouched, only the display name being changed.

Example 4. uac_replace_from usage

...
uac_replace_from("Smith","sip:[email protected]");
	- replaces both display name and URI with the
	given values
uac_replace_from("","sip:[email protected]");
	- replaces only the URI with the given value,
	the display name being removed
uac_replace_from("Smith","");
	- leaves the URI untouched and replaces just
	the display name with the given value
...
				

4.2.  uac_replace_from(uri)

Replaces only the FROM URI with the new uri value. The FROM display name is kept untouched.

Function returns true only if the replacement operation was successfully completed.

Meaning of the parameters is as follows:

  • uri - the new value for the FROM URI - it must be a non-empty valid SIP URI.

Example 5. uac_replace_from usage

...
uac_replace_from("sip:[email protected]");
	- replace only the URI with the given value,
	the display name being kept untouched
...
				

4.3.  uac_restore_from()

The function restores the changed value of FROM URI to the original value. The restoring is based on the stored value in the from_store_param. Since the changed FROM URI may appear as TO within the dialog requests which are generated by UAS, the function checks the FROM header for replies and TO header for requests.

The function does nothing if the from_restore_mode is set to NO RESTORE (0).

The function can be called for both request and reply messages from all types of routes (REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE).

Example 6. uac_restore_from usage

...
uac_restore_from();
...
				

4.4.  uac_auth()

The function performs client Digest authentication. It can be called only from FAILURE_ROUTE. If the final reply is an authentication request (401 or 407), based on the defined credentials, it tries to match and inserts an authentication response header (Authorization or Proxy-Authorization). The credentials matching to the challenge is done based on username and realm.

The function returns true if an authentication response header was successfully inserted into the request.

NOTE: the CSeq number is not incremented upon a challenge which may make the function not to work with RFC-strict-compliant implementations.

Example 7. uac_auth usage

...
uac_auth();
...