Skip to content

README.md

Latest commit

 

History

History
109 lines (80 loc) · 6.48 KB

README.md

File metadata and controls

109 lines (80 loc) · 6.48 KB
Raw

Custom metadata

The WS-Discovery protocol tells Windows what kind of device it is exposing by sending over "metadata" - essentially an XML document containing information about the computer.

By default, wsdd-native sends metadata describing the host it is running on as an SMB server. It is possible to change that by authoring your own metadata and telling wsdd-native to use that instead.

To do so, you need to use the --metadata PATH (or -m PATH) command-line switch or put metadata="path" in the wsddn.conf file.

Format

Custom metadata must be a valid, well-formed, standalone XML file. All namespaces you use must be fully declared.

General form

The general form of the metadata is as follows. For more details, see this obscure spec.

<?xml version="1.0" encoding="UTF-8"?>
<wsx:Metadata 
    xmlns:wsx="http://schemas.xmlsoap.org/ws/2004/09/mex"
    xmlns:wsdp="http://schemas.xmlsoap.org/ws/2006/02/devprof"
    xmlns:pnpx="http://schemas.microsoft.com/windows/pnpx/2005/10" >
  <wsx:MetadataSection Dialect="http://schemas.xmlsoap.org/ws/2006/02/devprof/ThisDevice">
    <wsdp:ThisDevice>
        <wsdp:FriendlyName>...</wsdp:FriendlyName>
        <wsdp:FirmwareVersion>...</wsdp:FirmwareVersion>
        <wsdp:SerialNumber>...</wsdp:SerialNumber>
    </wsdp:ThisDevice>
  </wsx:MetadataSection>
  <wsx:MetadataSection Dialect="http://schemas.xmlsoap.org/ws/2006/02/devprof/ThisModel">
    <wsdp:ThisModel>
      <wsdp:Manufacturer>...</wsdp:Manufacturer>
      <wsdp:ModelName>...</wsdp:ModelName>
      <wsdp:ModelNumber>...</wsdp:ModelNumber>
      <pnpx:DeviceCategory>...</pnpx:DeviceCategory>
    </wsdp:ThisModel>
  </wsx:MetadataSection>
  <wsx:MetadataSection Dialect="http://schemas.xmlsoap.org/ws/2006/02/devprof/Relationship">
    <wsdp:Relationship Type="http://schemas.xmlsoap.org/ws/2006/02/devprof/host">
    ...
    </wsdp:Relationship>
  </wsx:MetadataSection>
</wsx:Metadata>

Placeholders

You can use placeholders inside XML element values and attributes. The placeholders are keywords that start with a $ sign.

The rules for placeholders are as follows:

  • A single $ not followed by a placeholder is simply dropped and ignored.
  • $$ is replaced with a single $.
  • The following placeholders are currently defined:
Placeholder Meaning
$ENDPOINT_ID Replaced with the URN in the form urn:uuid:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where the UUID is the identifier of the host. It is auto-generated or supplied via the --uuid option.
$IP_ADDR The IP address of the interface on which the metadata is being sent. This allows you to create URLs that operate on the same network that Windows "sees" your machine on.
$SMB_HOST_DESCRIPTION The description of the host as derived from SMB configuration. If no description is available, a simple SMB host name is used.
$SMB_FULL_HOST_NAME A string in the format hostname/Workgroup:workgroup_name or hostname/Domain:domain_name that provides the full SMB name of the machine in the WS-Discovery protocol.
  • Placeholders are prefix-matched, so $IP_ADDR_HELLO will be expanded to something like 192.168.1.1_HELLO.

Examples

This directory contains some examples that might help you author your own metadata.

The default.xml file contains an equivalent of what wsdd-native sends by default with no custom metadata. This is the standard metadata of an SMB host.

The other.xml file contains an example of a simple HTTP server. When you click on it in Windows Explorer, the browser would open pointing to that host. Where it points to is actually controlled by the line

<wsdp:PresentationUrl>http://$IP_ADDR/</wsdp:PresentationUrl>

which you can change to anything you want.

The section and icon in Windows Explorer Network view are determined by the line:

<pnpx:DeviceCategory>Other</pnpx:DeviceCategory>

In this example, it is Other, which would result in the host being in "Other devices". You can try other things here like HomeAutomation or MediaDevices. The full(?) list of what is allowed here can be divined from this obscure spec (warning: .doc file). See the table in the "PnPX Category Definitions" section.

More information

The entire area of what the actual WS-Discovery payload should be is incredibly poorly documented by Microsoft. The useful references (some already mentioned) I could find are as follows: