Legacy Document

Inside Macintosh: Networking /

Chapter 11 - Ethernet, Token Ring, and Fiber Distributed Data Interface / Ethernet, Token Ring, and FDDI Reference

Routines / Writing and Reading Ethernet Packets

ERead

When you use the default protocol handler for Ethernet that Apple provides, you must use the ERead function to read a data packet and place it in a data buffer.

FUNCTION ERead (thePBptr: EParamBlkPtr; async: Boolean): OSErr;

thePBptr

A pointer to a parameter block of type EParamBlock.

async

A Boolean value that specifies whether the function should be
executed asynchronously or synchronously. Specify TRUE for asynchronous execution.

-->	ioCompletion	ProcPtr	A pointer to completion routine.
<--	ioResult	OSErr	The result code.
-->	ioRefNum	Integer	The driver reference number.
-->	csCode	Integer	Always ENetRead for this function.
-->	eProtType	Integer	The Ethernet protocol type.
-->	ePointer	Ptr	A pointer to a data buffer.
-->	eBuffSize	Integer	The size of the data buffer.
<--	eDataSize	Integer	The number of bytes read.

Field Description

eProtType

The protocol type of the packet you want to read.

ePointer

A pointer to the data buffer into which you want to read data.

eBuffSize

The size of the data buffer. If you are expecting Ethernet data packets, the buffer should be at least 621 bytes in size; if you are expecting general Ethernet data packets, the buffer should be at least 1514 bytes in size.

eDataSize

The number of bytes of data actually read.

DESCRIPTION

You can use the ERead function to read packets of a particular protocol type only after you have used the EAttachPH function to specify a NIL pointer to the protocol handler to indicate that you want to use the default protocol handler. In practice, you should call the EAttachPH function very early, during your program initialization sequence, if possible. As soon as the connection is established and you are expecting data, you should call the ERead function asynchronously.

The ERead function places the entire packet, including the packet header, into your buffer. The function returns in the eDataSize parameter the number of bytes actually read. If the packet is larger than the data buffer, the ERead function places as much of the packet as will fit into the buffer and returns the buf2SmallErr result code.

Call the ERead function asynchronously to await the next data packet. When the .ENET driver receives the data packet, it completes execution of the ERead function and calls your completion routine. If the .ENET driver receives a data packet with a protocol type for which you specified the default protocol handler while no ERead command is pending, the driver discards the data packet.

You can have several asynchronous calls to the ERead function pending execution simultaneously as long as you use a different parameter block for each call.

SPECIAL CONSIDERATIONS

You must not use the ERead function to read packets if you supply and attach your own protocol handler. In this case, you use the driver's ReadPacket and ReadRest routines from within your protocol handler.

TOKEN RING AND FDDI CONSIDERATIONS

This function does not apply to token ring and FDDI.

ASSEMBLY-LANGUAGE INFORMATION

To execute the ERead function from assembly language, call the _Control trap macro with a value of ENetRead in the csCode field of the parameter block. To execute the _Control trap asynchronously, include the value ,ASYNC in the operand field.

RESULT CODES

noErr	0	No error
LAPProtErr	-94	No protocol is attached or protocol handler pointer was not 0
reqAborted	-1105	ERdCancel or EDetachPH function called
buf2SmallErr	-3101	Packet too large for buffer; partial data returned

SEE ALSO

See "Using the Default Ethernet Protocol Handler to Read Data" beginning on page 11-13 for more information on using the ERead function.