LibraryLink: What can we do with MInputStream and MOutputStream?

Question

Version 9 introduced the WolframStreamsLibrary.h header for LibraryLink. It contains MInputStream and MOutputStream.

What can I do with this header? How can I use these functions? Are the documented anywhere?

---

Possibly related:

• LibraryLink: What are DataStore and WolframIOLibrary?

---

Update 2018 March: Partial spelunking results, someone else may want to pick up the trail.

Currently, my best guess is that this is for extending Mathematica with new streams. I believe it to be the analogue of DefineInputStreamMethod and DefineOutputStreamMethod. The struct MInputStream contains most of the functions that would be passed to DefineInputStreamMethod. The actual analogue is registerInputStreamMethod in WolframLibray.h, which I believe sets the equivalents of the ConstructorFunction and NameTestFunction. My (unverified!) guesses for the parameters of registerInputStreamMethod are:

• const char *name, same as name in DefineInputStreamMethod
• void (*ctor)(MInputStream, const char* msgHead, void* optionsIn), same as "ConstructorFunction". Should fill out the MInputStream struct passed to it. But in what format does it receive the options?
• mbool (*handlerTest)(void*, char*), probably the same as "NameTestFunction". But what is the void * parameter for? The methodData?
• void* methodData, possibly pointer to private data used by the stream implementation.
• void (*destroyMethod)(void* methodData), possibly for freeing the methodData? This is not the "CloseFunction".

There are still many key questions remaining before one could actually implement everything that is needed.

What is the methodData? A state unique to each instance of the stream, or shared by all of them? (I assume this is shared, and the individual state is in the MInputStream struct.) What exactly should each of these functions do?

An example implementation is woefully needed. After some more spelunking, I found one in SystemFiles/Links/SocketLink/Source/C. This example may provide enough information for us to write our own implementation, but I have not yet had the time/motivation to do all this. I still wanted to share my findings with others who may be interested in continuing the spelunking.

Note that the SocketLink example won't answer all questions: it often passes NULL pointers or simply ignores arguments (e.g the options in the constructor).

Answer 1

MInputStream and MOutputStream are two classes in the LibraryLink API for Mathematica that provide functionality for reading from and writing to streams, respectively.

MInputStream is a class that represents an input stream, and it provides methods for reading data from the stream. Some of the common methods that can be used with MInputStream include:

read: Reads a byte from the stream and returns it as an integer. readDouble: Reads a double-precision floating-point number from the stream. readInt: Reads an integer from the stream. readString: Reads a string from the stream. MOutputStream, on the other hand, is a class that represents an output stream, and it provides methods for writing data to the stream. Some of the common methods that can be used with MOutputStream include:

write: Writes a byte to the stream. writeDouble: Writes a double-precision floating-point number to the stream. writeInt: Writes an integer to the stream. writeString: Writes a string to the stream. Both MInputStream and MOutputStream are useful when working with data streams, such as files or network sockets. For example, when writing a LibraryLink function that reads from a file, you can create an MInputStream object to represent the file stream, and then use the read methods to read data from the file. Similarly, when writing a LibraryLink function that writes to a file, you can create an MOutputStream object to represent the file stream, and then use the write methods to write data to the file.