Inside Macintosh: Interapplication Communication /

Chapter 11 - Program-to-Program Communications Toolbox

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

noErr	0	No error
paramErr	-50	Illegal parameter
memFullErr	-108	Not enough memory to load PPCBrowser package
userCanceledErr	-128	User decided not to conduct a session
notInitErr	-900	PPC Toolbox has not been initialized yet
nameTypeErr	-902	Invalid or inappropriate locationKindSelector in location name
noPortErr	-903	Unable to open port or bad port reference number
noGlobalsErr	-904	System unable to allocate memory, critical error
localOnlyErr	-905	Network activity is currently disabled
destPortErr	-906	Port does not exist at destination
sessTableErr	-907	PPC Toolbox is unable to create a session
noSessionErr	-908	Invalid session reference number
badReqErr	-909	Bad parameter or invalid state for this operation
portNameExistsErr	-910	Another port is already open with this name
noUserNameErr	-911	User name unknown on destination machine
userRejectErr	-912	Destination rejected the session request
noResponseErr	-915	Unable to contact application
portClosedErr	-916	The port was closed
sessClosedErr	-917	The session has closed
badPortNameErr	-919	PPC port record is invalid
noDefaultUserErr	-922	User has not specified owner name in Sharing Setup control panel
notLoggedInErr	-923	Default user reference number does not yet exist
noUserRefErr	-924	Unable to create a new user reference number
networkErr	-925	An error has occurred in the network
noInformErr	-926	PPCStart failed because target application did not have an inform pending
authFailErr	-927	User's password is wrong
noUserRecErr	-928	Invalid user reference number
badServiceMethodErr	-930	Service method is other than ppcServiceRealTime
badLocNameErr	-931	Location name is invalid
guestNotAllowedErr	-932	Destination port requires authentication
nbpDuplicate	-1027	Location name represents a duplicate on this computer