Skip to main content

mDNS-SD Configuration API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

Overview​

The mDNS-SD configuration API makes it possible to enable and disable the mDNS-SD (Multicast DNS Service Discovery) functionality, set and get the friendly name of a device, and make Discovery calls to find other devices on the local network.

Use cases​

Manage mDNS-SD​

Enable or disable mDNS-SD​

Set the mdnssd.v2.enabled property to enable or disable mDNS-SD.

Example:

curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2/enabled \
  --data '{
    "data": true
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Manage friendly name​

Use mdnssd.v2.friendlyName to check or change the friendly name.

Example:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2/friendlyName
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": "AXIS M1075-L - B8A44FE56631"
}
curl --request PATCH \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2/friendlyName \
  --data '{
    "data": "string"
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Make discovery call​

Make a discovery call to look for nearby devices with specific services.

This trigger will check for other mDNS-SD clients on the local network with services supplied in the services parameter. If multiple services are supplied, any client advertising any of the services will be discovered.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2/discovery \
  --data '{
    "data": {
        "services": [
            "_axis-video._tcp"
        ],
        "timeout": 2
    }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "deviceServices": [
                {
                    "serviceName": "_axis-video._tcp",
                    "servicePort": 80,
                    "serviceTxt": "macaddress=B8A44F1D58C3"
                }
            ],
            "friendlyName": "AXIS Q3536-LVE - B8A44F1D58C3",
            "hostname": "spechn-3.local.",
            "interface": "eth0",
            "ipv4Address": [
                "192.168.0.218"
            ],
            "ipv6Address": [
                "ccee:2da0:54ac:8a2f:baa4:4fff:fe1d:58c3",
                "fe80::baa4:4fff:fe1d:58c3"
            ]
        }
    ]
}

Custom errors​

Error codeError messageDescription
100Invalid requestmDNS-SD is disabled during a discovery call.

Example:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --http1.1 \
  --header "Content-Type: application/json" \
  http://my-device/config/rest/mdnssd/v2/discovery \
  --data '{
    "data": {
        "services": [
            "_axis-video._tcp"
        ],
        "timeout": 2
    }
}'
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "error",
    "error": {
        "code": 100,
        "message": "Backend defined error: \"mDNS-SD is not enabled, can not call discovery.\""
    }
}

API definition​

Structure​

mdnssd.v2 (Root Entity)
    ├── enabled (Property)
    ├── friendlyName (Property)
    ├── discovery (Action)

Entities​

mdnssd.v2​

  • Description: mDNS-SD configuration.
  • Type: Singleton
  • Operations
    • Get
  • Attributes
    • Dynamic Support: No
Properties​
enabled​
  • Description: The enabled state for mDNS-SD.
  • Datatype: boolean
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
friendlyName​
  • Description: The friendly name for mDNS-SD.
  • Datatype: string
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​
discovery​
  • Description: Discover devices in the network.
  • Request Datatype: DiscoveryData
  • Response Datatype: DiscoveryResponseData
  • Trigger Permissions: admin
  • Attributes
    • Dynamic Support: No

Data Types​

Device​

  • Description: Device found by discovery.
  • Type: complex
  • Fields
    • deviceServices
      • Description: The services this device offers.
      • Type: DeviceServiceList
      • Nullable: No / Gettable: Yes
    • friendlyName
      • Description: The friendlyname of the device.
      • Type: string
      • Nullable: No / Gettable: Yes
    • hostname
      • Description: The hostname of the device.
      • Type: string
      • Nullable: No / Gettable: Yes
    • interface
      • Description: On which local interface the device was discovered.
      • Type: string
      • Nullable: No / Gettable: Yes
    • ipv4Address
      • Description: A list of IPv4 addresses found on the device.
      • Type: StringArray
      • Nullable: No / Gettable: Yes
    • ipv6Address
      • Description: A list of IPv6 addresses found on the device.
      • Type: StringArray
      • Nullable: No / Gettable: Yes

DeviceService​

  • Description: A service which a discovered device offers.
  • Type: complex
  • Fields
    • serviceName
      • Description: The name of the service.
      • Type: string
      • Nullable: No / Gettable: Yes
    • servicePort
      • Description: The port on which the service may be found.
      • Type: integer
      • Nullable: No / Gettable: Yes
    • serviceTxt
      • Description: The text record of the service.
      • Type: string
      • Nullable: No / Gettable: Yes

DeviceServiceList​

  • Description: A list of DeviceServices.
  • Type: array
  • Element type: DeviceService
  • Null Value: No

DiscoveryData​

  • Description: Data type used for discovery.
  • Type: complex
  • Fields
    • services
      • Description: The services to look for during the discovery.
      • Type: ServiceList
      • Nullable: No / Gettable: Yes
    • timeout
      • Description: The timeout for how many seconds a discovery should last.
      • Type: Timeout
      • Nullable: No / Gettable: Yes

DiscoveryResponseData​

  • Description: Devices found through discovery.
  • Type: array
  • Element type: Device
  • Null Value: No

Service​

  • Description: A service for the discovery to discover.
  • Type: string
  • Pattern: ^_[A-Za-z0-9]A-Za-z0-9-_]{0,13}[A-Za-z0-9]\._(udp|tcp)$|^_[A-Za-z0-9]\.\_(udp|tcp)$

ServiceList​

  • Description: A list of services.
  • Type: array
  • Element type: Service
  • Null Value: No

StringArray​

  • Description: An array of strings.
  • Type: array
  • Element type: string
  • Null Value: No

Timeout​

  • Description: Valid timeout value in seconds.
  • Type: integer
  • Minimum Value: 1
  • Maximum Value: 15