Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Important: The information in this document is obsolete and should not be used for new development.
Summary of the PPC Toolbox
Pascal Summary
Constants
CONST {gestalt selectors} gestaltPPCToolboxAttr = 'ppc '; {PPC Toolbox attributes} gestaltPPCToolboxPresent = $0000; {PPC Toolbox is present} gestaltPPCSupportsRealTime = $1000; {real time only in system } { software version 7.0} gestaltPPCSupportsOutGoing = $0002; {support of outgoing } { sessions across a network} gestaltPPCSupportsIncoming = $0001; {user enabled program } { linking in Sharing Setup } { control panel} {service type) ppcServiceRealTime = 1; {real time only in System 7} {look-up type} ppcNoLocation = 0; {there is no PPCLocName} ppcNBPLocation = 1; {use AppleTalk NBP} ppcNBPTypeLocation = 2; {use just the NBP type, fill } { in the rest with default} {port type} ppcByCreatorAndType = 1; {port type is specified as } { standard creator and type} ppcByString = 2; {port type is in Pascal } { string format} {session request type returned in the PPCInform function} ppcLocalOrigin = 1; {session initiated on } { local computer} ppcRemoteOrigin = 2; {session initiated on } { remote computer}Data Types
TYPE PPCServiceType = SignedByte; {service type} PPCLocationKind = Integer; {look-up type} PPCPortKinds = Integer; {port type} PPCSessionOrigin = SignedByte; {local or remote} PPCPortRefNum = Integer; {port reference number} PPCSessRefNum = LongInt; {session reference number} LocationNamePtr = ^LocationNameRec; LocationNameRec = RECORD locationKindSelector: PPCLocationKind; {which variant} CASE PPCLocationKind OF {ppcNoLocation: storage not } { used by this value} ppcNBPLocation: {NBP name entity} (nbpEntity: EntityName); ppcNBPTypeLocation:(nbpType: Str32);{just the NBP type string } { for the PPCOpen function} END; PortInfoPtr = ^PortInfoRec; PortInfoRec = RECORD filler1: SignedByte; {space holder} authRequired: Boolean; {authentication required} name: PPCPortRec; {port name} END; PPCPortPtr = ^PPCPortRec; PPCPortRec = RECORD nameScript: ScriptCode; {script identifier} name: Str32; {port name shown in program } { linking dialog box} portKindSelector: PPCPortKinds; {general category of } { application} CASE PPCPortKinds OF ppcByString: (portTypeStr: Str32);{32 characters} ppcByCreatorAndType: {4-character creator and type} (portCreator: OSType; portType: OSType); END; PPCParamBlockPtr = ^PPCParamBlockRec; PPCParamBlockRec = RECORD CASE Integer OF 0: (openParam: PPCOpenPBRec); {PPCOPen params} 1: (informParam: PPCInformPBRec); {PPCInform params} 2: (startParam: PPCStartPBRec); {PPCStart params} 3: (acceptParam: PPCAcceptPBRec); {PPCAccept params} 4: (rejectParam: PPCRejectPBRec); {PPCReject params} 5: (writeParam: PPCWritePBRec); {PPCWrite params} 6: (readParam: PPCReadPBRec); {PPCRead params} 7: (endParam: PPCEndPBRec); {PPCEnd params} 8: (closeParam: PPCClosePBRec); {PPCClose params} 9: (listPortsParam: IPCListPortsPBRec); {IPCListPorts params} END; PortInfoArrayPtr = ^PortInfoArray; PortInfoArray = ARRAY[0..0] OF PortInfoRec; PPCOpenPBPtr = ^PPCOpenPBRec; PPCOpenPBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a } { completion routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} portRefNum: PPCPortRefNum; {PPC port identifier} filler1: LongInt; {space holder} serviceType: PPCServiceType; {real time only} resFlag: SignedByte; {reserved field} portName: PPCPortPtr; {name of port to be opened} locationName: LocationNamePtr; {location of port to be } { opened} networkVisible: Boolean; {port is visible for } { browsing} nbpRegistered: Boolean; {location name registered } { on network} END; PPCInformPBPtr = ^PPCInformPBRec; PPCInformPBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} portRefNum: PPCPortRefNum; {port identifier} sessRefNum: PPCSessRefNum; {session identifier} serviceType: PPCServiceType; {real time only} autoAccept: Boolean; {automatic session } { acceptance} portName: PPCPortPtr; {name of port that } { initiated a session} locationName: LocationNamePtr; {location of port that } { initiated a session} userName: StringPtr; {name of user that } { initiated a session} userData: LongInt; {application-defined} requestType: PPCSessionOrigin; {local or remote} END; PPCStartPBPtr = ^PPCStartPBRec; PPCStartPBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} portRefNum: PPCPortRefNum; {identifier for requested } { port} sessRefNum: PPCSessRefNum; {session identifier} serviceType: PPCServiceType; {real time only} resFlag: SignedByte; {reserved field} portName: PPCPortPtr; {name of port to be opened} locationName: LocationNamePtr; {location of port to be } { opened} rejectInfo: LongInt; {rejection of session} userData: LongInt; {application-specific} userRefNum: LongInt; {specifies an authenticated } { user} END; PPCAcceptPBPtr = ^PPCAcceptPBRec; PPCAcceptPBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} filler1: Integer; {space holder} sessRefNum: PPCSessRefNum; {session identifier} END; PPCRejectPBPtr = ^PPCRejectPBRec; PPCRejectPBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} filler1: Integer; {space holder} sessRefNum: PPCSessRefNum; {session identifier} filler2: Integer; {space holder} filler3: LongInt; {space holder} filler4: LongInt; {space holder} rejectInfo: LongInt; {rejection of session} END; PPCWritePBPtr = ^PPCWritePBRec; PPCWritePBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} filler1: Integer; {space holder} sessRefNum: PPCSessRefNum; {session identifier} bufferLength: Size; {length of buffer to be } { written} actualLength: Size; {actual size of data written} bufferPtr: Ptr; {location of buffer to be } { written} more: Boolean; {additional data to be } { written} filler2: SignedByte; {space holder} userData: LongInt; {application-specific} blockCreator: OSType; {creator of block to be } { written} blockType: OSType; {type of block to be written} END; PPCReadPBPtr = ^PPCReadPBRec; PPCReadPBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} filler1: Integer; {space holder} sessRefNum: PPCSessRefNum; {session identifier} bufferLength: Size; {length of buffer to be read} actualLength: Size; {actual size of the data } { read} bufferPtr: Ptr; {location of buffer to be } { read} more: Boolean; {additional data to be read} filler2: SignedByte; {space holder} userData: LongInt; {application-specific} blockCreator: OSType; {creator of block to be read} blockType: OSType; {type of block to be read} END; PPCEndPBPtr = ^PPCEndPBRec; PPCEndPBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} filler1: Integer; {space holder} sessRefNum: PPCSessRefNum; {identifier of session to } { be terminated} END; PPCClosePBPtr = ^PPCClosePBRec; PPCClosePBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} portRefNum: PPCPortRefNum; {identifier of port to } { be closed} END; IPCListPortsPBPtr = ^IPCListPortsPBRec; IPCListPortsPBRec = RECORD qLink: Ptr; {private} csCode: Integer; {private} intUse: Integer; {private} intUsePtr: Ptr; {private} ioCompletion: PPCCompProcPtr; {address of a completion } { routine} ioResult: OSErr; {completion of operation} reserved: ARRAY[1..5] OF LongInt; {private} filler1: Integer; {space holder} startIndex: Integer; {index to the port entry } { list} requestCount: Integer; {number of entries to } { be returned} actualCount: Integer; {actual number of port names} portName: PPCPortPtr; {list of port names} locationName: LocationNamePtr; {location of port names} bufferPtr: PortInfoArrayPtr; {pointer to a buffer} END;PPC Toolbox Routines
Initializing the PPC Toolbox
FUNCTION PPCInit: OSErr;Using the Program Linking Dialog Box
FUNCTION PPCBrowser(prompt: Str255; applListLabel: Str255; defaultSpecified: Boolean; VAR theLocation: LocationNameRec; VAR thePortInfo: PortInfoRec; portFilter: PPCFilterProcPtr; theLocNBPType: Str32): OSErr;Obtaining a List of Ports
FUNCTION IPCListPorts(pb: IPCListPortsPBPtr; async: Boolean): OSErr;Opening and Closing a Port
FUNCTION PPCOpen(pb: PPCOpenPBPtr; async: Boolean): OSErr; FUNCTION PPCClose(pb: PPCClosePBPtr; async: Boolean): OSErr;Starting and Ending a Session
FUNCTION PPCStart(pb: PPCStartPBPtr; async: Boolean): OSErr; FUNCTION StartSecureSession(pb: PPCStartPBPtr; VAR userName: Str32; useDefault: Boolean; allowGuest: Boolean; VAR guestSelected: Boolean; prompt: Str255) : OSErr; FUNCTION PPCEnd(pb: PPCEndPBPtr; async: Boolean): OSErr;Receiving, Accepting, and Rejecting a Session
FUNCTION PPCInform(pb: PPCInformPBPtr; async: Boolean): OSErr; FUNCTION PPCAccept(pb: PPCAcceptPBPtr; async: Boolean): OSErr; FUNCTION PPCReject(pb: PPCRejectPBPtr; async: Boolean): OSErr;Reading and Writing Data
FUNCTION PPCRead(pb: PPCReadPBPtr; async: Boolean): OSErr; FUNCTION PPCWrite(pb: PPCWritePBPtr; async: Boolean): OSErr;Locating a Default User and Invalidating a User
FUNCTION GetDefaultUser(VAR userRef: LongInt; VAR userName: Str32) : OSErr; FUNCTION DeleteUserIdentity(userRef: LongInt): OSErr;Application-Defined Routines
PROCEDURE MyCompletionRoutine (pb: PPCParamBlockPtr); FUNCTION MyPortFilter(locationName: LocationNameRec; thePortInfo: PortInfoRec): Boolean;C Summary
Constants
CONST enum { /*gestalt selectors*/ #define gestaltPPCToolboxAttr 'ppc ' /*PPC Toolbox attributes*/ gestaltPPCToolboxPresent = $0000, /*PPC Toolbox is present*/ gestaltPPCSupportsRealTime = $1000, /*real time only in system */ /* software version 7.0*/ gestaltPPCSupportsOutGoing = $0002, /*support of outgoing */ /* sessions across a network*/ gestaltPPCSupportsIncoming = $0001 /*user enabled program */ /* linking in Sharing Setup */ /* control panel*/ }; enum { /*service type*/ ppcServiceRealTime = 1 /*real time only in System 7*/ }; enum { /*look-up type*/ ppcNoLocation = 0, /*there is no PPCLocName*/ ppcNBPLocation = 1, /*use AppleTalk NBP*/ ppcNBPTypeLocation = 2 /*use just the NBP type, fill */ /* in the rest with default*/ }; enum { /*port type*/ ppcByCreatorAndType = 1, /*port type is specified as */ /* standard Mac creator and type*/ ppcByString = 2 /*port type is in Pascal */ /* string format*/ }; enum { /*session request type returned in the PPCInform function*/ ppcLocalOrigin = 1, /*session initiated on */ /* local computer*/ ppcRemoteOrigin = 2 /*session initiated on */ /* remote computer*/ };Data Types
typedef unsigned char PPCServiceType; /*service type*/ typedef short PPCLocationKind; /*look-up type*/ typedef short PPCPortKinds; /*port type*/ typedef unsigned char PPCSessionOrigin; /*local or remote*/ typedef short PPCPortRefNum; /*port reference number*/ typedef long PPCSessRefNum; /*session reference number*/ struct PPCPortRec { ScriptCode nameScript; /*script identifier*/ Str32 name; /*port name shown in program */ /* linking dialog box*/ PPCPortKinds portKindSelector; /*general category of */ /* application*/ union Str32 portTypeStr; /*32 characters*/ struct OSType creator; /*4-character creator and */ OSType type; /* type*/ } port; } u; }; typedef struct PPCPortRec PPCPortRec; typedef PPCPortRec *PPCPortPtr; struct LocationNameRec { PPCLocationKind locationKindSelector; /*which variant*/ union { EntityName nbpEntity; /*NBP name entity*/ Str32 nbpType; /*just the NBP type string */ /* for the PPCOpen function*/ } u; }; typedef struct LocationNameRec LocationNameRec; typedef LocationNameRec *LocationNamePtr; struct PortInfoRec { unsigned char filler1; /*space holder*/ Boolean authRequired; /*authentication required*/ PPCPortRec name; /*port name*/ }; typedef struct PortInfoRec PortInfoRec; typedef PortInfoRec *PortInfoPtr; typedef PortInfoRec *PortInfoArrayPtr; typedef pascal Boolean (*PPCFilterProcPtr) (LocationNamePtr, PortInfoPtr); /*procedures you need to write*/ /*ex: void MyCompletionRoutine(PPCParamBlkPtr pb)*/ /*ex: pascal Boolean MyPortFilter(LocationNamePtr, PortInfoPtr)*/ typedef ProcPtr PPCCompProcPtr; #define PPCHeader \ Ptr qLink; /*private*/ unsigned short csCode; /*private*/ unsigned short intUse; /*private*/ Ptr intUsePtr; /*private*/ PPCCompProcPtr ioCompletion; /*address of a */ /* completion routine*/ OSErr ioResult; /*completion of operation*/ unsigned long Reserved[5]; /*private*/ struct PPCOpenPBRec { PPCHeader PPCPortRefNum portRefNum; /*PPC port identifier*/ long filler1; /*space holder*/ PPCServiceType serviceType; /*real time only*/ unsigned char resFlag; /*reserved field*/ PPCPortPtr portName; /*name of port to be opened*/ LocationNamePtr locationName; /*location of port to be */ /* opened*/ Boolean networkVisible; /*port is visible for */ /* browsing*/ Boolean nbpRegistered; /*location name registered */ /* on network*/ }; typedef struct PPCOpenPBRec PPCOpenPBRec; typedef PPCOpenPBRec *PPCOpenPBPtr; struct PPCInformPBRec { PPCHeader PPCPortRefNum portRefNum; /*port identifier*/ PPCSessRefNum sessRefNum; /*session identifier*/ PPCServiceType serviceType; /*real time only*/ Boolean autoAccept; /*automatic session acceptance*/ PPCPortPtr portName; /*name of port that */ /* initiated a session*/ LocationNamePtr locationName; /*location of port that */ /* initiated a session*/ StringPtr userName; /*name of user that */ /* initiated a session*/ unsigned long userData; /*application-defined*/ PPCSessionOrigin requestType; /*local or remote*/ }; typdef struct PPCInformPBRec PPCInformPBPtr; struct PPCStartPBRec { PPCHeader PPCPortRefNum portRefNum; /*identifier for requested */ /* port*/ PPCSessRefNum sessRefNum; /*session identifier*/ PPCServiceType serviceType; /*real time only*/ unsigned char resFlag; /*reserved field*/ PPCPortPtr portName; /*name of port to be opened*/ LocationNamePtr locationName; /*location of port to be opened*/ unsigned long rejectInfo; /*rejection of session*/ unsigned long userData; /*application-specific*/ unsigned long userRefNum; /*specifies an authenticated user*/ }; typedef struct PPCStartPBRec PPCStartPBRec; typedef PPCStartPBRec *PPCStartPBPtr; struct PPCAcceptPBRec { PPCHeader short filler1; /*space holder*/ PPCSessRefNum sessRefNum; /*session identifier*/ }; typedef struct PPCAcceptPBRec PPCAcceptPBRec; typedef PPCAcceptPBRec *PPCAcceptPBPtr; struct PPCRejectPBRec { PPCHeader short filler1; /*space holder*/ PPCSessRefNum sessRefNum; /*session identifier*/ short filler2; /*space holder*/ long filler3; /*space holder*/ long filler4; /*space holder*/ unsigned long rejectInfo; /*rejection of session*/ }; typedef struct PPCRejectPBRec PPCRejectPBRec; typedef PPCRejectPBRec *PPCRejectPBPtr; struct PPCWritePBRec { PPCHeader short filler1; /*space holder*/ PPCSessRefNum sessRefNum; /*session identifier*/ Size bufferLength; /*length of buffer to be written*/ Size actualLength; /*actual size of data written*/ Ptr bufferPtr; /*location of buffer to be */ /* written*/ Boolean more; /*additional data to be written*/ unsigned char filler2; /*space holder*/ unsigned long userData; /*application-specific*/ OSType blockCreator; /*creator of block to be written*/ OSType blockType; /*type of block to be written*/ }; typedef struct PPCWritePBRec PPCWritePBRec; typedef PPCWritePBRec *PPCWritePBPtr; struct PPCReadPBRec { PPCHeader short filler1; /*space holder*/ PPCSessRefNum sessRefNum; /*session identifier*/ Size bufferLength; /*length of buffer to be read*/ Size actualLength; /*actual size of the data read*/ Ptr bufferPtr; /*location of buffer to be read*/ Boolean more; /*additional data to be read*/ unsigned char filler2; /*space holder*/ unsigned long userData; /*application-specific*/ OSType blockCreator; /*creator of block to be read*/ OSType blockType; /*type of block to be read*/ }; typedef struct PPCReadPBRec PPCReadPBRec; typdef PPCReadPBRec *PPCReadPBPtr; struct PPCEndPBRec { PPCHeader short filler1; /*space holder*/ PPCSessRefNum sessRefNum; /*identifier of session to */ /* be terminated*/ }; typedef struct PPCEndPBRec PPCEndPBRec; typedef PPCEndPBRec *PPCEndPBPtr; struct PPCClosePBRec { PPCHeader PPCPortRefNum portRefNum; /*identifier of port to */ /* be closed*/ }; typedef struct PPCClosePBRec PPCClosePBRec; typedef PPCClosePBRec *PPCClosePBPtr; struct IPCListPortsPBRec { PPCHeader short filler1; /*space holder*/ unsigned short startIndex; /*index to the port entry list*/ unsigned short requestCount; /*number of entries to */ /* be returned*/ unsigned short actualCount; /*actual number of port names*/ PPCPortPtr portName; /*list of port names*/ LocationNamePtr locationName; /*location of port names*/ PortInfoArrayPtr bufferPtr; /*pointer to a buffer*/ }; typedef struct IPCListPortsPBRec IPCListPortsPBRec; typedef IPCListPortsPBRec *IPCListPortsPBPtr; union PPCParamBlockRec { PPCOpenPBRec openParam; /*PPCOpen params*/ PPCInformPBRec informParam; /*PPCInform params*/ PPCStartPBRec startParam; /*PPCStart params*/ PPCAcceptPBRec acceptParam; /*PPCAccept params*/ PPCRejectPBRec rejectParam; /*PPCReject params*/ PPCWritePBRec writeParam; /*PPCWrite params*/ PPCReadPBRec readParam; /*PPCRead params*/ PPCEndPBRec endParam; /*PPCEnd params*/ PPCClosePBRec closeParam; /*PPCClose params*/ IPCListPortsPBRec listPortsParam; /*IPCListPorts params*/ }; typdef union PPCParamBlockRec PPCParamBlockRec; typdef PPCParamBlockRec *PPCParamBlockPtr;PPC Toolbox Routines
Initializing the PPC Toolbox
pascal OSErr PPCInit(void);Using the Program Linking Dialog Box
pascal OSErr PPCBrowser(ConstStr255Param prompt, ConstStr255Param applListLabel, Boolean defaultSpecified, LocationNameRec *theLocation, PortInfoRec *thePortInfo, PPCFilterProcPtr portFilter, ConstStr32Param theLocNBPType);Obtaining a List of Ports
pascal OSErr IPCListPorts(IPCListPortsPBPtr pb, Boolean async);Opening and Closing a Port
pascal OSErr PPCOpen(PPCOpenPBPtr pb, Boolean async); pascal OSErr PPCClose(PPCClosePBPtr pb, Boolean async);Starting and Ending a Session
pascal OSErr PPCStart(PPCStartPBPtr pb, Boolean async); pascal OSErr StartSecureSession (PPCStartPBPtr pb, Str32 userName, Boolean useDefault, Boolean allowGuest, Boolean *guestSelected, ConstStr255Param prompt); pascal OSErr PPCEnd(PPCEndPBPtr pb, Boolean async);Receiving, Accepting, and Rejecting a Session
pascal OSErr PPCInform(PPCInformPBPtr pb, Boolean async); pascal OSErr PPCAccept(PPCAcceptPBPtr pb, Boolean async); pascal OSErr PPCReject(PPCRejectPBPtr pb, Boolean async);Reading and Writing Data
pascal OSErr PPCRead(PPCReadPBPtr pb, Boolean async); pascal OSErr PPCWrite(PPCWritePBPtr pb, Boolean async);Locating a Default User and Invalidating a User
pascal OSErr GetDefaultUser(unsigned long *userRef, Str32 userName); pascal OSErr DeleteUserIdentity (unsigned long userRef);Application-Defined Routines
void MyCompletionRoutine(PPCParamBlockPtr pb); pascal Boolean MyPortFilter(LocationNameRec locationName, PortInfoRec thePortInfo);Assembly-Language Summary
Trap Macros
Trap Macros Requiring Routine Selectors
_Pack9
Selector Routine $0D00 PPCBrowser_PPC
Selector Routine $0000 PPCInit $0001 PPCOpen $0002 PPCStart $0003 PPCInform $0004 PPCAccept $0005 PPCReject $0006 PPCWrite $0007 PPCRead $0008 PPCEnd $0009 PPCClose $000A IPCListPorts $000C DeleteUserIdentity $000D GetDefaultUser $000E StartSecureSession Result Codes