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

OpenersNotesSection(Spacer1)Details and Options

An input stream method can provide a new source of bytes, a way to filter a stream of bytes, or a combination of both.

The following stream functions can be provided:

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

Each (RefLink[InputStream, paclet:ref/InputStream]) 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 input 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 reading, the "ConstructorFunction" is called. It opens a stream indicated by streamname, which could be a file name, URL, or other resource identification appropriate to the stream method. The caller argument is a symbol for issuing messages. The calling function, such as (RefLink[OpenRead, paclet:ref/OpenRead]), will complete its creation of an (RefLink[InputStream, paclet:ref/InputStream]) 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 reading from the stream include:

"ReadFunction" is the essential function for reading from the stream. It takes an argument n and returns a list of n bytes, integers ranging from 0 to 255. Fewer bytes may be returned if the stream is at the end of file, or if there is an error while reading. In that case, "EndOfFileQFunction" and "ErrorTextFunction" are used to determine the cause. If no "ReadFunction" is provided, the default definition returns an empty list of bytes.

"EndOfFileQFunction" is used in the process of reading from the stream, and a stream method should typically provide this function. This function should return (RefLink[True, paclet:ref/True]) when the last byte of the stream has been returned by the "ReadFunction". The default definition returns (RefLink[True, paclet:ref/True]).

"WaitForInputFunction" is used in the process of reading from a stream. This method is useful for stream methods that read from a source where input may be available intermittently, such as from a pipe to another process. In such a case, a stream method's "ReadFunction" should ensure that it never waits for input and only returns as many bytes as available; "WaitForInputFunction" is the place where it waits for input. The default definition does nothing.

Functions for reading and setting the stream size and position are as follows:

"StreamPositionFunction" is used to support (RefLink[StreamPosition, paclet:ref/StreamPosition]). The position result is an integer that specifies the position of the current point in the open stream. A position of -1 indicates that the stream position is unknown. The default definition returns a position of -1.

"StreamSizeFunction" is used in the process of reading from the stream. A stream method that provides this function with an accurate stream size may perform faster than a stream method that does not. The size result is an integer that specifies the total number of bytes in the stream, or -1 if the size is unknown. The default definition returns a size of -1.

"SeekableQFunction" is used to support (RefLink[SetStreamPosition, paclet:ref/SetStreamPosition]). A stream method that provides a "SeekFunction" should provide a "SeekableQFunction" that returns (RefLink[True, paclet:ref/True]). The default definition returns (RefLink[False, paclet:ref/False]).

"SeekFunction" is used to support (RefLink[SetStreamPosition, paclet:ref/SetStreamPosition]). If a stream method does not support setting the stream position, this function does not need to be provided, but "SeekableQFunction" should return (RefLink[False, paclet:ref/False]). This function is called with offset, which is either a non-negative integer indicating a byte position relative to the start of the stream, or (RefLink[Infinity, paclet:ref/Infinity]) indicating the position at the end of the stream. This function should return (RefLink[True, paclet:ref/True]) to indicate that the seek succeeded.

Functions for handling errors are as follows:

"ErrorTextFunction" is used in the process of reading from 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 "ReadFunction" returns fewer bytes than requested and "EndOfFileQFunction" returns (RefLink[False, paclet:ref/False]). 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.

"OptionChangesFunction" is used to edit the options for a stream st from the list returned by (RefLink[Options, paclet:ref/Options])[st,(RefLink[Method, paclet:ref/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  (3)

OpenersExampleSection0(Spacer1)Basic Examples  (1)

Define a stream method that takes its input from a list of bytes, passed as a method option "Bytes":

DefineInputStreamMethod["ByteList",{
"ConstructorFunction"->
Function[{name,caller,opts},If[MatchQ[opts,{___,"Bytes"->{_Integer ...},___}],
{True,{0,"Bytes"/.opts}},
{False,$Failed}
]],

"ReadFunction"->
Function[{state,n},
Module[{pos=state[[1]],bytes=state[[2]],bytesRead},
If[pos>=Length[bytes],
{{},state},
bytesRead=Part[bytes,pos+1;;Min[Length[bytes],pos+n]];
{bytesRead,{pos+Length[bytesRead],bytes}}
]
]],

"EndOfFileQFunction"->({#[[1]]>=Length[#[[2]]],#}&)
}]

Open a stream to a list of bytes, which could have come from anywhere:

bytes=ToCharacterCode["Title: The Quick Brown Fox\nAbstract: A fox jumps over dogs.\nThe quick brown fox jumped over the lazy dogs.\n"];
st=OpenRead["Quick Brown Fox",Method->{"ByteList","Bytes"->bytes}]

Read from the stream:

ReadList[st,String]

Close the stream:

Close[st]

OpenersExampleSection1(Spacer1)Scope  (1)

A stream method that does not define seek methods will work, but the kernel will need to use more memory to support certain operations. This shows that more and more bytes are read on successive read calls to fill a growing buffer:

DefineInputStreamMethod["Passthrough",
 {
  "ConstructorFunction" -> 
Function[{streamname,caller,opts},
With[{state=Unique["PassthroughStream"]},
state["stream"]=OpenRead[streamname,BinaryFormat->True];
state["eof"]=False;
{True,state}
]],

"CloseFunction"->Function[state,Close[state["stream"]];ClearAll[state]],

"ReadFunction" ->
 Function[{state,nBytes},
Module[{bytes=If[state["eof"]===True,{},BinaryReadList[state["stream"],"Byte",nBytes]]},
If[!ListQ[bytes],bytes={}];
Print["Read ", Length[bytes]," bytes"];
state["eof"]=Length[bytes]<nBytes;
{bytes,state}
]],

"EndOfFileQFunction" -> Function[state,{state["eof"],state}]
  }
]

st=OpenRead[FindLibrary["demo"],BinaryFormat->True,Method->"Passthrough"];
data=BinaryReadList[st];
Close[st];
RemoveInputStreamMethod["Passthrough"]

By adding support for "SeekableQFunction", "StreamSize", and "SeekFunction", the read buffer remains the same size:

DefineInputStreamMethod["Passthrough",
 {
  "ConstructorFunction" -> 
Function[{streamname,caller,opts},
With[{state=Unique["PassthroughStream"]},
state["stream"]=OpenRead[streamname,BinaryFormat->True];
state["eof"]=False;
state["streamsize"]=FileByteCount[streamname];
{True,state}
]],

"CloseFunction"->Function[state,Close[state["stream"]]; ClearAll[state]],

"ReadFunction" ->
 Function[{state,nBytes},
Module[{bytes=If[state["eof"]===True,{},BinaryReadList[state["stream"],"Byte",nBytes]]},
If[!ListQ[bytes],bytes={}];
Print["Read ", Length[bytes]," bytes"];
state["eof"]=Length[bytes]<nBytes;
{bytes,state}
]],

"EndOfFileQFunction" -> Function[state,{state["eof"],state}],

"SeekableQFunction"->Function[state,{True,state}],

"StreamSizeFunction"->Function[state,{state["streamsize"],state}],

"SeekFunction"->
Function[{state,newpos},
SetStreamPosition[state["stream"],newpos];
{True,state}]
  }
]
st=OpenRead[FindLibrary["demo"],BinaryFormat->True,Method->"Passthrough"];
data=BinaryReadList[st];
Close[st];
RemoveInputStreamMethod["Passthrough"]

OpenersExampleSection3(Spacer1)Neat Examples  (1)

Define an input stream method that opens a stream to a file inside a zip archive:

Needs["JLink`"];
InstallJava[];
Map[LoadJavaClass,{"java.util.zip.ZipEntry","java.util.zip.ZipFile",
"java.io.InputStream"}];
General::zipentry="Option required for ZipFile input stream method was missing: \"Entry\"->path";
General::nozipentry="Specified value for \"Entry\" was not found in the zip archive: `1`";
DefineInputStreamMethod["ZipFile",{
"ConstructorFunction"->
Function[{src,caller,opts},
With[{state=Unique["ZipFileStream"]},
Module[{entry,zipFile,zipEntry},
entry="Entry"/.opts;
If[entry==="Entry",
Message[caller::zipentry];
{False,Null}
,
state["entry"]=entry;zipFile=JavaNew["java.util.zip.ZipFile",src];
zipEntry=zipFile@getEntry[entry];
state["instrm"]=Quiet[zipFile@getInputStream[zipEntry]];
If[JavaObjectQ[state["instrm"]],
state["pos"]=0;
state["size"]=Null;
state["eof"]=False;
{True,state}
,
Message[caller::nozipentry,entry];
{False,Null}
]
]]]],

"CloseFunction"->Function[state,
state["instrm"]@close[];
 ClearAll[Evaluate[state]];
 ],

"EndOfFileQFunction"->Function[state,{TrueQ[state["eof"]],state}],

"StreamPositionFunction"->Function[state,{state["pos"],state}],

"StreamSizeFunction"->Function[state,{state["size"]/.{Null->-1,n_:>n},state}],

"ReadFunction"->
Function[{state,nBytes},
Module[{byte,bytes,buff,bytesRead,reading=True},
buff=state["buff",nBytes];
If[!JavaObjectQ[buff],
buff=state["buff",nBytes]=JavaNew["[B",nBytes]
];
bytesRead=state["instrm"]@read[buff];
bytes=Take[JavaObjectToExpression[buff],Max[0,bytesRead]];
state["pos"]=state["pos"]+bytesRead;
If[bytesRead<nBytes,
state["eof"]=True;
state["size"]=state["pos"];
];
{bytes,state}
]],

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

Open a stream to a text file inside a jar file:

jarpath=First@Select[JavaClassPath[],FileNameTake[#,-1]==="wolfram-remote-services-client.jar"&]
st=OpenRead[jarpath,Method->{"ZipFile","Entry"->"com/wolfram/remoteservices/build.properties"}]

Read the lines from it:

ReadList[st,String]

Close the stream and release its resources:

Close[st]

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

({{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])}})}})