({{, (RefLink[DefineOutputStreamMethod, paclet:ref/DefineOutputStreamMethod])["name",{"(Subscript[fname, 1])"->(Subscript[function, 1]),"(Subscript[fname, 2])"->(Subscript[function, 2]),… }] 
defines a custom output stream method with the specified name, allowing the Wolfram Language to call the stream functions for opening and writing to an output stream.}})

OpenersNotesSection(Spacer1)Details

An output stream method can provide a new destination for bytes, a way to filter a stream of bytes, or a combination of both.

Output stream method functions are as follows:

Only the "ConstructorFunction" must be supplied to (RefLink[DefineOutputStreamMethod, paclet:ref/DefineOutputStreamMethod]). Other functions have a default behavior if a function is not provided.

Each (RefLink[OutputStream, paclet:ref/OutputStream]) opened with a stream method has a current state. This is where a stream method can store information such as a handle to the underlying stream resource, the current stream position, the latest error message, and other information needed by the stream method functions. The initial state expression is returned by "ConstructorFunction". Other functions take the current state as a parameter and return a new state value.

If a function returning a new state value is not provided, the default definition returns the given state unmodified.

Functions for opening and closing an output stream are:

"NameTestFunction" is needed when the stream is opened with (RefLink[Method, paclet:ref/Method])->(RefLink[Automatic, paclet:ref/Automatic]), and the Wolfram Language needs to choose a stream method to use based on streamname. A stream method will be used if its "NameTestFunction" returns (RefLink[True, paclet:ref/True]). If no "NameTestFunction" is provided, the default behavior is to return (RefLink[False, paclet:ref/False]).

When a stream is opened for writing, the "ConstructorFunction" is called. It opens a stream indicated by streamname that could be a file name, URL, or other resource identification appropriate to the stream method. The isAppend argument is (RefLink[True, paclet:ref/True]) if the stream was opened for appending and (RefLink[False, paclet:ref/False]) if it was opened for writing a new resource. The caller argument is a symbol for issuing messages. The calling function, such as (RefLink[OpenWrite, paclet:ref/OpenWrite]), will complete its creation of an (RefLink[OutputStream, paclet:ref/OutputStream]) if success is (RefLink[True, paclet:ref/True]). The state is used as the initial value of the stream method's state.

"CloseFunction" is used for a stream st when (RefLink[Close, paclet:ref/Close])[st] is called. Resources allocated in the "ConstructorFunction" should be deallocated here. The default definition does nothing.

Functions for writing to the stream include:

"WriteFunction" is the essential function for writing to the stream. The byteCount result is the number of bytes successfully written to the stream. The default definition returns a byteCount of 0.

"FlushFunction" is used to support the process of writing to a stream. It should ensure that any bytes passed to the "WriteFunction" are transferred from memory buffers to the stream. The result of this function is ignored. The format of this function is:

If no "FlushFunction" is provided, the following definition is used:

Functions for handling errors are as follows:

"ErrorTextFunction" is used in the process of writing to the stream. It should return an error message (RefLink[String, paclet:ref/String]) if there is an error condition and (RefLink[Null, paclet:ref/Null]) if there is no error. The Wolfram Language will call this function if other functions indicate failure, for example, if "WriteFunction" indicates that it wrote fewer bytes than requested. The default definition returns a result of (RefLink[Null, paclet:ref/Null]).

"ClearErrorFunction" is called if "ErrorTextFunction" returned an error string and is called to clear the error state. After this, "ErrorTextFunction" should return (RefLink[Null, paclet:ref/Null]) until there is another error reading from the stream. The result of this function is ignored. It is recommended that a stream method providing an "ErrorTextFunction" should also provide a "ClearErrorFunction" definition.

"StreamPositionFunction" is used to support (RefLink[StreamPosition, paclet:ref/StreamPosition]). The position result is an integer that specifies the number of bytes written to the stream with "WriteFunction". The default definition returns -1.

"OptionChangesFunction" is used to edit the options for a stream st from the list returned by (RefLink[Options, paclet:ref/Options])[st,Method]. For example, a stream method may take an option that includes a password or other piece of sensitive security data. By default, (RefLink[Options, paclet:ref/Options]) will return that setting. This function provides a way to remove that option field. The format of this function is:

OpenersPrimaryExamplesSection(Spacer1)Examples  (1)

OpenersExampleSection0(Spacer1)Basic Examples  (1)

Define a stream method that writes to a list of bytes, retrieved as a stream option:

DefineOutputStreamMethod["ByteList",{
"ConstructorFunction"->
Function[{name,isAppend,caller,opts},{True,{}}],

"WriteFunction"->
Function[{state,bytes},{Length[bytes],Join[state,bytes]}],

"OptionChangesFunction"->Function[{state,opts},{Append[opts,"Bytes"->state],state}]
}]

Open a new stream using this method:

st=OpenWrite["Quick Brown Fox",FormatType->OutputForm,Method->"ByteList"]

Use the stream:

Write[st,"The quick brown fox"]

Write[st,"jumped over the lazy dogs."]

Retrieve the byte list:

output="Bytes"/.Rest[Method/.Options[st]]

FromCharacterCode[output]

Close[st]

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(RefLink[RemoveOutputStreamMethod, paclet:ref/RemoveOutputStreamMethod])}})}})

({{DocumentationFooterIconsRelatedTutorial.png, ({{Tutorials}, {▪(RefLinkPlain[Stream Methods, paclet:tutorial/StreamMethods])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Stream Methods, paclet:guide/StreamMethods])}, {▪(RefLinkPlain[Low-Level File Operations, paclet:guide/LowLevelFileOperations])}})}})