Legacy Document

Inside Macintosh: Networking /

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

Routines / Attaching and Detaching an Ethernet Protocol Handler

EAttachPH

The EAttachPH function attaches a protocol handler to the .ENET driver to receive packets of a particular protocol type. You can provide and attach your own protocol handler or use the default protocol handler provided by Apple.

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

thePBptr

A pointer to a parameter block of type EParamBlock.

async

A Boolean value that specifies whether the function is to 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 ENetAttachPH for this function.
-->	eProtType	Integer	The Ethernet protocol type.
-->	ePointer	Ptr	A pointer to protocol handler.

Field Description

eProtType

The protocol type for which you are attaching a protocol handler. To attach a protocol handler for Ethernet Phase 1 packets, specify 0 as the value of this field. (Ethernet Phase 1 packets are IEEE 802.3 protocol packets.)

ePointer

A pointer to your protocol handler application. To use the default protocol handler that Apple provides, set this field value to NIL.

DESCRIPTION

The EAttachPH function serves two purposes: you can use it to attach to the .ENET driver your own protocol handler for a specific protocol type, or you can use it to specify that the .ENET driver should call the default protocol handler for your protocol type. If you attach your own protocol handler, the .ENET driver calls that protocol handler each time it receives a packet with the protocol type you specified. If you specify that the .ENET driver should use the default protocol handler, then you use the ERead command to read packets with that protocol type. In practice, you should call the EAttachPH function very early, during your program initialization sequence, if possible.

You specify the protocol type in the eProtType parameter and provide a pointer to the protocol handler in the ePointer parameter. If you specify NIL for the ePointer parameter, then the .ENET driver uses the default protocol handler for that protocol type.

SPECIAL CONSIDERATIONS

Instead of using the EAttachPH function to install a protocol handler for an Ethernet Phase 2 packet, you should use the LAP Manager's L802Attach routine. In the case of an 802.3 protocol packet, the .ENET driver passes the packet to the LAP Manager 802.2 protocol handler. If the packet has the protocol type you specified with the L802Attach routine, the LAP Manager passes the packet on to your protocol handler. For information about the L802Attach routine, see the chapter "Link-Access Protocol (LAP) Manager" in this book.

TOKEN RING AND FDDI CONSIDERATIONS

This function is available for token ring and FDDI also. However, Apple Computer, Inc. recommends that you use the LAP Manager's L802Attach routine instead to attach your protocol handlers for token ring and FDDI. For information about the L802Attach routine, see the chapter "Link-Access Protocol (LAP) Manager" in this book.

Note that if you use this function for token ring or FDDI, you exclude other processes, such as AppleTalk, from attaching their protocol handlers to the driver at the same time. If you use the LAP Manager interface, other applications can also attach their protocol handlers and use the driver concurrently.

If you use this function for token ring, you can only install a protocol handler for protocol type 0. To use this function for either token ring or FDDI, you must set the ioRefNum field to the driver reference number that the OpenSlot or the OpenDriver function returns.

Apple does not provide a default protocol handler for token ring or FDDI.

ASSEMBLY-LANGUAGE INFORMATION

To execute the EAttachPH function from assembly language, call the _Control trap macro with a value of ENetAttachPH 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	Protocol handler is already attached or node's protocol table is full

SEE ALSO

For more information on how to use the EAttachPH function, see "Using the Default Ethernet Protocol Handler to Read Data" beginning on page 11-13.

For information on the IEEE 802.2 and 802.3 protocols, see the chapter "Link-Access Protocol (LAP) Manager" in this book.