Before we get started, I do recommend you re-read my original post on WSDXML.  The relationship between WSDXML_ELEMENT, WSDXML_TYPE, and WSDXML_NODE is an important part of understanding how everything fits together.

Simple example: element with text
The first example will demonstrate how to build a single element with text, but without any attributes or children.  If we imagine the "ex" prefix is bound to the https://www.example.org namespace, here's the element we will want to build:

        <ex:TestElement>text</ex:TestElement>

Creating this structure is straightforward.  It involves two steps:

1. Extract an XML name ("ex:TestElement") from the XML context
2. Build a WSDXML_ELEMENT structure from that XML name

Here's what it looks like in code.

        // All error handling is omitted from this example
        HRESULT hr = S_OK;
        IWSDXMLContext *pContext = NULL;
        WSDXML_NAME *pName = NULL;
        WSDXML_ELEMENT *pElement = NULL;

        hr = WSDXMLCreateContext( &pContext );

        hr = pContext->AddNamespace(
                L"https://www.example.org",
                L"ex",
                NULL );

        hr = pContext->AddNameToNamespace(
                L"https://www.example.org",
                L"TestElement",
                &pName );

        hr = WSDXMLBuildAnyForSingleElement(
                pName,  // pName is copied here, and must be freed separately
                L"text",
                &pElement );

        // pElement is now complete, and contains: <ex:TestElement>text</ex:TestElement>

        // cleanup:
        // WSDFreeLinkedMemory( pElement );
        // WSDFreeLinkedMemory( pName );
        // pContext->Release();

Note that you can omit the "text" parameter to WSDXMLBuildAnyForSingleElement to generate empty elements.  Supplying NULL here would result in <ex:TestElement />

Advanced example: chaining elements
We'll build on the last example to show how you can create chains of structures.  Here's the element we want to build this time:

        <ex:ParentElement>
            <ex:ChildElement>text</ex:ChildElement>
            <ex:AnotherChildElement />
        </ex:ParentElement>

In this case, the steps go like this:

1. Build ParentElement, ChildElement, and AnotherChildElement separately using the instructions above.
2. Use WSDXMLAddChild to link ParentElement to ChildElement
3. Use WSDXMLAddChild or WSDXMLAddSibling to add in AnotherChildElement.  Either is acceptable.

Important: see section below on cleaning up WSDXML structures.  Also note that you only need to call IWSDXMLContext::AddNamespace once for a given namespace--it is not necessary to call it for every name you add.

Here's some example code:

        // Use steps above to create pParentElement, pChildElement,
        //     and pAnotherChildElement

        hr = WSDXMLAddChild( pParentElement, pChildElement );

        hr = WSDXMLAddSibling( pChildElement, pAnotherChildElement );
        // It is also acceptable to call
        // WSDXMLAddChild( pParentElement, pAnotherChildElement);

        // cleanup:
        // WSDFreeLinkedMemory( pParentElement );
        // Use WSDFreeLinkedMemory to destroy WSDXML_NAME objects
        //     extracted from IWSDXMLContext
        // DO NOT FREE pChildElement or pAnotherChildElement;
        //     they are attached to pParentElement

Destroying WSDXML structures
At first glance, it may seem complex to destroy these structures, but they're designed to be simple.  You only need to follow a few simple rules to write robust and leak-free WSDXML code:

• All WSDXML functions use linked memory.  Always use WSDFreeLinkedMemory to destroy individual structures or whole trees.
• WSDXMLBuildAnyForSingleElement copies the "name" parameter and links a copy into the new tree.
• WSDXMLAddChild and WSDXMLAddSibling link together all structures in the tree.
• Only free the topmost WSDXML_ELEMENT structure in an entire tree.
• When passing WSDXML structures as outparams from services, be sure to link the entire WSDXML tree into the outparameter.

The links to the RDDL and spec pages currently point to the Committee Specification 1 (CS1) revisions of the specs, but OASIS will update these links to the fully standardized versions of the documents soon.

This is a big milestone in the progress of these specifications.  My thanks go to the other members of the WS-DD Technical Committee, who all showed great dedication to this technology, and many of whom made substantial commitments of time and energy in producing high-quality specifications.

In short, MTOM is a way to link binary MIME attachments into the SOAP envelope*.  The simplest example is a print job: using MTOM, you can send a SOAP message that describes the print job, and attach the binary document as a MIME attachment inside the HTTP connection.  MTOM lets you link the MIME and SOAP together.  This seems like an obvious way to package data, but let's imagine what would happen without that binding: the sender would have to encode the binary document into some form (likely base64) and then inline it into the SOAP message.  There are a lot of disadvantages in this approach, most notably that the receiver can't really process the SOAP until it consumes the entire binary document, which could be very large.  This would be a huge problem for devices, which are often memory-limited and which rely on streaming large documents as they cannot buffer them in entirety.

That last sentence hints at a neat fringe benefit of MTOM: it allows the sender and receiver to establish a binary stream with a SOAP message header.  This is a really convenient way to open a stream like this, since the stream can coexist on the port used to send SOAP traffic, and there's a natural association between the strongly-typed SOAP contents and the more flexible stream data.  Conceptually, MTOM doesn't distinguish between well-bounded documents and open-ended streams, although solutions are often written with either one of these in mind.

A good example of the stream pattern is the DPWS-based Windows SideShow Bitmap driver, which uses the SendSideShowFrameStream operation to open a stream connection, which is linked inside the FrameStream element.  The SOAP message contains some useful parameters about the stream, and the stream contains bitmaps.

There are, naturally, disadvantages and limitations to this approach.  The stream itself is unidirectional (although you may be able to set up simultaneous request/response streams), and even though a SOAP message can contain multiple MTOM sections, only one stream can be active at a time.  Every stream must be prefaced with a SOAP message, and the data inside is completely untyped.  But even with these limitations, using MTOM to set up streams is incredibly handy in DPWS applications.

To use MTOM in your application, simply include the xs:base64Binary schema type in an element.  This type will become a pointer to the MIME section containing your binary document or stream data.  WSDAPI automatically interprets this type and provides IWSDAttachment pointers for easy access to the binary data.

* Note: MTOM is actually a bit more complex than this, and is organized into a generic optimization mechanism and a MIME serialization.  But in the context of DPWS, it really is just a way to link MIME sections into SOAP.

Even though these aren't approved standards, we can still compare the technical details of DPWS v1.0 (the version originally supported in Vista) to the latest revision of DPWS v1.1 to see what has changed.

• Namspaces:  First and foremost, DPWS v1.1 (and WS-Discovery v1.1) have new namespaces.  This means that the two protocols are not inherently compatible--instead, individual implementers may choose whether they will support v1.0, v1.1, or both.  In my opinion, the lack of backward compatibility built into the specification is actually a good thing: it keeps the specs isolated and individually very simple, and does not burden future specs written on DPWS v1.1 with a requirement to support the pre-standard versions of the specs.
• References: The v1.1 revisions now reference the latest available standards, particularly WS-Policy v1.5 and WS-Addressing v1.0.  Note that references to WS-Transfer, WS-MetadataExchange, and WS-Eventing have not yet been updated as those specifications are still being standardized in the W3C WS-RA WG.
• Security:  DPWS v1.1 features a heavily reorganized security section which is simpler, easier to understand from an implementation perspective, and better organized.  I'm personally very pleased with this change, as it makes DPWS security even more accessible.
• Numerous smaller changes: I can't really do justice to the many other meaningful changes made to improved the quality of the specifications.  Across all three specs, we resolved 141 issues ranging from a few editorial updates to dramatic improvements in specific parts of the text.

I also want to call out one big change to WS-Discovery:

• WS-Discovery Managed Mode:  WS-Discovery v1.1 now clearly separates two functional modes: ad-hoc, where discovery occurs among peers; and managed, where discovery occurs by means of a discovery proxy.  WS-Discovery v1.0 hinted at how this would work but v1.1 is much clearer about how clients and services can contact a proxy.

Now, there are many changes I'm lumping into that category of "numerous smaller changes" which could each be broken out into their own articles--but the items I've listed above are the ones I'm most excited about.  In the future I expect to dive into these (particularly security) in much greater detail.

Stay tuned for additional updates as the OASIS member vote on these specs gets underway.

One of the great uses of WS-Discovery is transforming logical addresses into physical addresses (e.g., https://my_pc/service/) so you can actually contact the service.  A service uses the xAddrs field in WS-Discovery messages to express its transport addresses.

But it turns out that these xAddrs are optional.  There are actually a lot of really good cases why you would want to omit them--if they're very large, or if you don't want to generate different Hello messages for every IP address in the system--but the specification doesn't clearly explain when they're often omitted in the real world, and what happens when they are.

So let's go through the four messages a service can send.

• Hello messages sometimes contain xAddrs.  On any given subnet it's likely to encounter Hello messages both with and without xAddrs.  Those without xAddrs will cause a Resolve from any clients interested in the service.  Hello is the only multicast message that can include xAddrs, so it's a little unique--and it differs from ProbeMatches and ResolveMatches in that sense.
• Bye messages never contain xAddrs.  The specification does not allow it (note that this has been changed in WS-Discovery v1.1).
• ResolveMatches messages always contain xAddrs.  It's technically possible for the xAddrs element to be empty but this is unusual and probably not a good way to achieve interoperability.  A service must realistically always produce xAddrs in its ResolveMatches messages.
• ProbeMatches messages usually contain xAddrs.  It's very unusual for services to omit xAddrs in their ProbeMatches messages because it takes no more effort than including them in ResolveMatches--both messages are unicast responses.  Including xAddrs in ProbeMatches lets everyone avoid a Resolve/ResolveMatches exchange.

One interesting consequence of this is that the example sequence on page 11 of WS-Discovery (Probe -> ProbeMatches -> Resolve -> Resolve Matches -> success!) almost never happens.  Services usually include xAddrs in their ProbeMatches messages in the first place.

Of these two, the device-level metadata is the most important.  Since WS-Discovery only advertises the Device, the device-level metadata is the only way to discover the services.  Without device-level metadata, you really can't do anything with the device.  WSDAPI and Windows relies heavily on device-level metadata to populate the properties visible inside the Network explorer, and this metadata is retrieved any time an application attempts to use a Hosted Service on the device.

The service-level metadata, on the other hand, isn't absolutely critical for Windows to connect to the device.  It is possible that someone will build an application that uses service-level metadata (the IWSDServiceProxy::BeginGetMetadata/EndGetMetadata methods provide access) but for now it's not used by many of the applications that ship inside Windows.

When DPWS is involved, things are a little more complicated.  Remember that DPWS uses a Host service that is responsible for advertising all of the Hosted services.  The Hosted services are the ones that actually perform the device's functionality (e.g., WSD Toaster operations) so their types are advertised in the metadata that the Host service provides (e.g., the Host service would describe a Hosted service, and would advertise a type of t:WSDToasterService).

Now in most cases, the Host service does not actually implement any application-specific operations on its own; it only provides the metadata that allows a client to find the application-specific services.  Devices built like this don't advertise t:WSDToasterService at the device level because it's inaccurate--a client cannot send WSD Toaster operations directly to the Host service and expect them to work.  The Host service supports the WS-Transfer/Get request used to retrieve the device's metadata, that that operation is described by the dpws:Device type.

The difficulty is that clients cannot search for devices that support WSD Toaster services at the WS-Discovery layer.  After all, why should a device connect to hundreds of devices that have nothing to do with WSD Toaster?

To fix this problem, some specifications add an empty device-layer type with no associated operations, but which identifies that one or more service-layer types of interest can be found on this device.  So in this case, WSD Toaster would define a type t:WSDToasterDevice without any associated actions, but which is required on every device with a matching t:WSDToasterService service.  Clients can then merely search for t:WSDToasterDevice in WS-Discovery and only retrieve metadata for devices that contain toaster services.  t:WSDToasterDevice isn't useful on its own, but it does provide a hint that t:WSDToasterService is nearby.

DPWS v1.0 applications usually manually describe the association between their service-layer (t:WSDToasterService) and device-layer (t:WSDToasterDevice) types in normative text.  It usually looks something like this: "A device that supports one or more WSD Toaster services MUST advertise the t:WSDToasterDevice type at the DPWS DEVICE."  As a convenience, DPWS v1.1 Appendix C adds an optional WSDL attribute that can be used to express this association in a way that code generation tools can understand.  An example is shown in that appendix.

Now, this article doesn't completely describe the possible variations of these types, and the benefits and drawbacks of any of the arrangements.  Specification authors should be warned that this is a complex topic and shouldn't be taken lightly--at some point I may even put together a whole post on how to choose the layout.  But the basics I've described here are applicable to many of the most common cases (including WS-Print and WS-Scan), and should provide some clarity to specification authors, application-layer implementers, and generic stack implementers alike.

As I mentioned in my earlier posts, this is a very important step for these specifications as the entire DPWS community comes together to collaborate on the specifications and refine and improve the contents.  In fact, this technical committee has filed and handled nearly 150 different issues across all three specifications, and has improved the utility and broad applicability of the specs without changing the core fundamentals set out in the 1.0 versions.

Although the dates have slipped a little, it is expected that the specs will enter the 60-day OASIS public review period shortly, bringing us even closer to the date when DPWS will be a standard.

Ultimately, you should always refer to the documentation, as rules for specific objects may differ from the norm.  But in most cases, the following guidelines apply:

• Terminate should always be called if the object was properly initialized, and should be called before calling Release.  Terminate often does last-minute cleanup work that cannot occur inside Release, such as synchronizing threads, or cleaning other objects that may have references back to this object.  Failing to call Terminate could result in access violations as other threads continue to run, or could result in reference loops and leaks.
• Release should always be called when you're discarding a reference to the object.  Release should be called even if Terminate is also required.

Often, my cleanup code looks like this:

HRESULT hr = S_OK;
IWSDDeviceHost *pDeviceHost = NULL;

hr = WSDCreateDeviceHost( ..., &pDeviceHost );

// ...initialize and use pDeviceHost...

if( NULL != pDeviceHost )
{
    // Always terminate pDeviceHost if it was successfully created/initialized
    hr = pDeviceHost->Terminate();
    // Optionally print an error if Terminate failed

    // Always release pDeviceHost, even if Terminate failed
    pDeviceHost->Release();
    pDeviceHost = NULL;
}

And things are about to get even more complicated--but for very good reason--with the introduction of the Windows Web Services API (WWSAPI).  Even though it means one more stack to choose from, I'm actually very excited about WWSAPI, because it brings WCF-like functionality to native non-managed Windows applications.  This fills a big gap in the development story for Web Services.

So soon there will be at least three different stacks you can use to build WS applications.

• Web Services on Devices API (WSDAPI) is the one-stop shop for building applications on DPWS, WSD, or WS-Discovery.  If you use any of these three technologies, use WSDAPI.  (And if you're lost in the acronyms, see this post.)
• Windows Communication Foundation (WCF) is the generic Web Services stack available in .NET.  If you're not communicating with devices but are using managed code, use WCF.
• Windows Web Services API (WWSAPI) is the generic Web Services stack available on Windows.  If you're not communicating with devices but are using native code, use WWSAPI.

Additionally, there are other technology-specific WS stacks available in Windows (such as WinRM for WS-Management) that I'm not listing here for brevity.

The short version is that if you're using devices, WSDAPI is probably the first place to look for Web Services connectivity.  For more generic Web Services applications, WWSAPI is a great solution if you're writing native code.

More information on WWSAPI can be found on the blogs of two WWSAPI team members, Hao Xu and Nikola Dudar.