Reads the specified number of bytes from the stream and discards them.

Namespace:  Quanser.Communications
Assembly:  Quanser.Communications (in Quanser.Communications.dll)

Syntax

Visual Basic (Declaration)
Public Function Ignore ( _
	numBytes As Integer _
) As Integer
C#
public int Ignore(
	int numBytes
)
Visual C++
public:
int Ignore(
	int numBytes
)
JavaScript
function ignore(numBytes);

Parameters

numBytes
Type: System..::.Int32
The number of bytes to read from the stream and ignore.

Return Value

The number of bytes received, which may be less than numBytes bytes for non-blocking streams. If no more data is available and the connection has been closed gracefully then 0 is returned. If no bytes are received and the method would block then -ErrorCode.WouldBlock is returned for non-blocking streams. If an error occurs then a StreamException is thrown.

Remarks

This method receives data over a client stream. However this data is simply discarded. It is not returned to the caller. It attempts to receive numBytes bytes from the communication channel.

If Listen or Connect was called with the non-blocking flag set to false, then this method blocks until all the data is read. If the connection has been closed gracefully then it returns 0 only once there is no more data to receive. Otherwise it returns the number of bytes read before the connection closed. Once all the data in the stream buffer is exhausted it will return 0 to indicate the connection has been closed. If an error occurs, then it throws a StreamException.

If Listen or Connect was called with the non-blocking flag set to true, then this method does not block. If no data is available at all then it returns -ErrorCode.WouldBlock. In this case, the Poll(Timeout, Int32) method may be used with the Receive flag to determine when data becomes available. Otherwise it returns the number of bytes received.

This method does not support two threads calling Ignore(Int32) or Receive at the same time. However, Send or Flush()()() may be called by another thread at the same time as Ignore(Int32).

The semantics of this method differ from the BSD recv() socket function because it receives numBytes bytes in blocking mode rather than the number of bytes that were sent in a single send() call at the peer. The semantics differ because this method attempts to "read ahead" by keeping the stream buffer full, thereby minimizing the number of receive operations performed on the internal connection. Also, due to buffering of the Send operation, the number of send() calls made at the peer may not correspond to the number expected.

Examples

This example connects to a remote host serving on TCP/IP port 18000. It assumes the peer is sending a 32-bit integer followed by a double. It ignores the integer but receives the double. This example uses blocking I/O.
C# Copy Code
Stream    stream            = new Stream();
String    uri               = "tcpip://localhost:18000";
int       sendBufferSize    = 1024;
int       receiveBufferSize = 1024;
bool      done              = false;
double [] buffer            = new double [1];

try {
    stream.Connect(uri, sendBufferSize, receiveBufferSize);

    try {
        while (!done) {
            /* 
                Ignore the 32-bit integer (4 bytes) sent but receive the double that follows it.
                If either method returns 0 then the peer has closed the connection gracefully.
            */
            if (stream.Ignore(4) == 0 || stream.Receive(buffer) == 0) {
                done = true;
            } else {
                /* ... process data received ... */
            }
        }
    } catch (Exception ex) {
        Console.WriteLine("Error communicating with client on URI '" + uri + "'. " + ex);
    }

    stream.Close();
} catch (Exception ex) {
    Console.WriteLine("Unable to connect to URI '" + uri + "'. " + ex);
}
Visual Basic Copy Code
Dim stream As New Stream()
Dim uri As String = "tcpip://localhost:18000"
Dim sendBufferSize As Integer = 1024
Dim receiveBufferSize As Integer = 1024
Dim done As Boolean = False
Dim buffer(0) As Double ' array of 1 double

Try
    stream.Connect(uri, sendBufferSize, receiveBufferSize);

    Try
        While Not done
            ' Ignore the 32-bit integer (4 bytes) sent but receive the double that follows it.
            ' If either method returns 0 then the peer has closed the connection gracefully.
            If stream.Ignore(4) = 0 or stream.Receive(buffer) = 0 Then
                done = True
            Else
                ' ... process data received ...
            End If
        End While
    Catch ex As Exception
        Console.WriteLine("Error communicating with client on URI '" & uri & "'. " & ex.ToString())
    End Try

    stream.Close()
Catch ex As Exception
    Console.WriteLine("Unable to connect to URI '" & uri & "'. " & ex.ToString())
End Try
Visual C++ Copy Code
Stream^  stream            = new Stream();
String^  uri               = L"tcpip://localhost:18000";
int      sendBufferSize    = 1024;
int      receiveBufferSize = 1024;
bool     done              = false;

array<double>^ buffer = gcnew array<double>(1);

try {
    stream->Connect(uri, sendBufferSize, receiveBufferSize);

    try {
        while (!done) {
            /* 
                Ignore the 32-bit integer (4 bytes) sent but receive the double that follows it.
                If either method returns 0 then the peer has closed the connection gracefully.
            */
            if (stream->Ignore(4) == 0 || stream->Receive(buffer) == 0) {
                done = true;
            } else {
                /* ... process data received ... */
            }
        }
    } catch (Exception ex) {
        Console::WriteLine("Error communicating with client on URI '" + uri + "'. " + ex);
    }

    stream->Close();
} catch (Exception ex) {
    Console::WriteLine("Unable to connect to URI '" + uri + "'. " + ex);
}

Exceptions

ExceptionCondition
Quanser.Communications..::.StreamException If an error occurs then an exception is thrown. This situation typically arises if an error has occurred in the underlying communication channel, such as the connection being lost unexpectedly.

See Also