References ▼
The format of the string for ONVIF streaming is as follows (optional components are enclosed in square brackets):
onvif[s]://[username[:password]@]ip_address[:port]/server_URL[?param1=val1[¶m2=val2]...[¶mN=valN]]
onvifu://[username[:password]@]uuid[?param1=val1[¶m2=val2]...[¶mN=valN]]
The following table describes the parameters of the string for ONVIF streaming:
| Component | Description |
|---|---|
| ip_address or uuid | (Mandatory) The server's IP address or universally unique identifier. Typically, ONVIF servers use DHCP to obtain an IP address automatically. The servers usually provide a utility for detecting the server's IP address. This can be in the usual IPv4 format (xx.xx.xx.xx), or it can be a valid host address accepted by the standard inet_addr function. For example, localhost is equivalent to 127.0.0.1. This is usually the IP address of the sending (server) computer. |
| It is also possible for a device to be accessed through a UUID. This is a special URL which uniquely identifies the ONVIF API endpoint of a device. The advantage of this method is that it is not IP-address-specific, and can connect to a device after a DHCP IP address change. | |
| The IP address for the server should be unicast. Even when requesting a multicast connection to an ONVIF server, use a unicast connection to the server. In multicast connections, the server will open separate multicast connections for broadcasting the data. But when connecting to the server, connect to a unicast address. | |
| username | (Optional) For servers that use authentication, a username must be passed as part of the connection string. |
| password | (Optional) For servers that use authentication, a password must be passed as part of the connection string. |
| server_URL | The server's web service endpoint. The standard server URL is "/onvif/device_service", but not all devices follow the standard. In such cases, consult the server's manual to obtain it. |
| paramN=valN | (Optional) Extra parameters used to modify the filter's or server's behavior. Parameters can be filter parameters (for example, G726Reversed=1), or server parameters (for example, ONVIFProfile=MyProfile). |
| The parameters used by the filter are listed below. Any parameters not listed below are considered server-dependent and are passed along to the server: | |
| • ONVIFProfile - (Optional) This parameter is a string that sets which ONVIF profile to use. The first available profile is used by default. | |
| • G726Reversed - (Optional) This parameter indicates whether the G726 data is reverse-encoded. The default value is 0. Set to 1 to enable. | |
| • EnableSecurityUI - (Optional) This parameter indicates whether to show or hide the username/password UI for ONVIF servers requiring a username and password. | |
| • 0 - Hides the username/password UI. This is the default value. | |
| • 1 - Shows the username/password UI. | |
| If set to 0, the RTSP source will fail to stream from RTSP servers using security, unless the correct username/password are entered in the URL. If the RTSP server requires a username/password and the URL does not contain the correct username/password, the filter will fail load or play the stream with the LTMM_E_RTSP_UNAUTHORIZED (0x80050037) error code. | |
To set this value programmatically, call the ILMONVIFSrc::EnableSecurityUI property. |
This protocol prefix supports standard non-secure connections, secure connections using SSL, and WS-discovery endpoint connections.
onvif://username:password@address:port/server_URL - An unencrypted connection to the ONVIF device (typical)
onvifs://username:password@address:port/server_URL - An encrypted connection to the ONVIF device
onvifu://username:password@uuid - A special URL used to browse (broadcast search) for a device using a unique identifier to get its endpoint
Notes:
Any extra parameters passed in the ONVIF URL will be provided to the ONVIF API endpoint. If the underlying source is an RTSP stream, these extra parameters will not be passed along to the RTSP server.
Most devices should be discoverable using the Browse button in the ONVIF property page. However, some devices can be configured to not be discoverable. It is also possible that the device could be on a different network, and therefore not discoverable. In either case you would be forced to enter a full URL with the IP address.
If the filter is unable to connect to retrieve the requested stream, the WS_E_ENDPOINT_ACCESS_DENIED error code will be returned. This error can also be returned if authentication fails (username & password required).
onvif://admin:admin@192.168.1.142/onvif/device_service - Connect to an ONVIF device running on 192.168.1.142 with both the username and password "admin".
onvifs://admin:admin@192.168.1.142/onvif/device_service?ONVIFProfile=Profile2 - Connect securely to an ONVIF device running on 192.168.1.142 with both the username and password "admin". The stream sent should conform to the profile named "Profile2".
onvifu://admin:admin@4519e6f6-692c-431f-ecfc-b0c55400b099?ONVIFProfile=MyProfile - Connect to an ONVIF device using its unique identifier using a custom profile.
Note: The UUID of a device can be obtained using the search mechanism in the ONVIF Source Filter Property. See the LEAD ONVIF Source User Interface topic for more information.