Where do I find conceptual documentation for Windows Runtime? [closed]

Question

I'm trying to learn enough about Windows Runtime to make a recommendation about what it would entail for my employer to port our existing applications to it. I'm having trouble finding documentation that provides a technical overview of how the API works.

All my web searches seem to lead me to API reference on MSDN, which is terse to the point of unreadability. It documents the formal signatures of API classes and methods, but seems to assume that the reader already knows how things fit together. The purpose of each method is usually just described as a terse sentence fragment that restates its name with spaces instead of CamelCase, and further explanations about restrictions, expectations and invariants beyond what is evident in the type declarations are almost completely absent. (This contrasts with the fairly informative "Remarks" sections in the reference documentation of the ordinary Win32 API).

Clearly, I'm not supposed to be using this documentation to develop an initial overview of how the API works. What am I supposed to be using?

Moving one level up in MSDN there is a section with the promising name Concepts and architecture, and some even more promising-sounding Programming concepts and Fundamentals -- but what they actually describe is a seemingly random selection of fairly specialized topics, certainly not what I need to make sense of the API reference.

Is there official documentation in book form that I need to buy and read? Something outside of MSDN? A secret MSDN link that I haven't been able to find?

I've seen this previous question which didn't get any real answers, perhaps because the it was phrased rather opaquely with $5 words like "ontology". In an attempt to explain better what I'm looking for, here are some examples of questions I hope the documentation I seek would tell me the answers to:

(Note that these are examples only. My primary goal is to find a specification that answers these and similar questions, rather than get answers to these specific examples.)

Windows.Networking.Sockets.StreamSocket has an InputStream property of type Windows.Storage.Streams.IInputStream, which I'm clearly supposed to use to read from the socket. But the only method of IInputStream is ReadAsync which reads into an IBuffer, and IBuffer is an interface that declares nothing but capacity and size properties. How do I get at the actual bytes being read? If I implement IBuffer myself, how will the system deliver them to me?

After hours of frustrated clicking and googling, I have tentatively concluded that the interface is a lie -- IBuffer is not something anyone can implement, but ReadAsync wants specifically a Windows.Storage.Streams.Buffer (without the I), no matter what its type declaration says. Then it seems I can use DataReader to read the actual bytes from the Buffer. Is that really how it's supposed to go?

or

Hmm, it looks like DataReader has a constructor that takes an IInputStream, so perhaps I can cut out the Buffer middleman after all. However, this seems to be wrong, because DataReader's methods such as ReadBytes are synchronous and supposedly all I/O in WinRT is asynchronous; certainly the one declared method of IInputStream is. So how does that work?

After more frustrated googling and clicking: Oh, there's a LoadAsync method in DataReader that does ... something. According to MSDN, it "loads data from the input stream", but what are the conventions for using it? Am I supposed to call it just once immediately after constructing the DataReader, or can I call it multiple times to reuse the same DataReader for the next read operation? Does DataReader contain a circular buffer internally? What happens if I try to read more bytes than have been read asynchronously already? The super-terse documentation of the ReadFoo methods mention no exceptions or error conditions; neither do the class documentation for DataReader or IDataReader.

or

Apparently apps can be multi-threaded, since the supported Win32 APIs include things like InterlockedCompareExchange, EnterCriticalSection and so forth. But neither CreateThread nor the RTL's _beginthreadex seem to be supported, and there doesn't appear to be any Java-ish Thread class anywhere in the WinRT class hierarchy. How does one start a new thread?

or

Speaking about asynchronous I/O ... I'm quite comfortable with the general idea of asynchronous I/O and completion continuations, but what are the precise rules in WinRT for, say, which thread the completion routine is called in? If it's always the same thread I started the I/O operation from (which I hope!), do I need to make sure it enters some kind of alertable wait from time to time, so the system has a chance to call my code there?

or

Wikipedia claims that "WinRT is essentially a COM-based API, although relying on an enhanced COM." What exactly is this "enhancement"? If I follow COM rules and conventions, do I risk being bitten by things that work differently due to "enhancements"? Or, conversely, is there things I can do easier because of the enhancement?

or

The only description of how asynchronous callbacks work make it look like they are quite specific to the implementation language -- it looks fairly different between C#/CLR, JavaScript and C++/CX. What's actually happening at the COM/ABI level here? In particular, since the API documentation appears to assume that "C++" means "C++/CX", how does asynchronous I/O work if I use WRL instead? Or is it just the case that the await and then business is just language-provided sugar and the real ABI is always in terms of AsyncOperationWithProgressCompletedHandler and so forth, as described in the API reference? But that's a delegate type; does that even have a well-defined meaning in terms of COM?

Answer 1

I've just noticed that there seem to be two parallel page hierarchies on MSDN describing the WinRT API:

• Windows Store app development | API Reference | Windows API reference for Windows Store apps

This is the almost vacuous documentation I rant about in the question. However, some of the API elements are also described in

• MSDN Library | Additional Resources | Windows Runtime C++ reference

which is slightly closer to the COM metal, and occasionally contains useful Remarks sections. For example its page for IBuffer reveals that implementations of IBuffer must also implement IBufferByteAccess which provides access to the actual bytes.

It is not ideal (and still seems to leave a lot of information implicit), but it is at least something.

Answer 2

I think this post could be a http://chat.stackoverflow.com/ debate, but not a question. WinRT Api and projections (c#/xaml or html/js etc.) references are in their first release and from my point of view at this time they are just a basic reference, not a extense documentation source.

This happpen usually with all recently created technologies, I think you just need to wait a couple of months and documentation will start to improve gradually.