Inside Macintosh: Interapplication Communication /

Chapter 11 - Program-to-Program Communications Toolbox

This chapter describes how you can use the Program-to-Program Communications (PPC) Toolbox to send and receive low-level message blocks between applications.

The PPC Toolbox can be used by different applications located on the same computer or across a network of Macintosh computers. The PPC Toolbox is available only in
System 7 or later. To test for the existence of the PPC Toolbox, use the Gestalt function, described in Inside Macintosh: Operating System Utilities.

Read this chapter if you want your application to transmit and receive data from other applications that support the PPC Toolbox. Applications that utilize the PPC Toolbox must be open and connected to each other to exchange data. The PPC Toolbox allows you to send large amounts of data to other applications; it is typically useful for code that is not event-based. The PPC Toolbox is called by the Macintosh Operating System and can also be called by applications, device drivers, desk accessories, or other programs.

The PPC Toolbox provides a method of communication that is particularly useful for applications that are specifically designed to work together and are dependent on each other for information. For example, suppose one user organizes large amounts of data using a database application and another user filters and plots the same data using a plotting application. If both applications use the PPC Toolbox, these two applications can directly transmit data to each other when both applications are open and connected to each other.

You can also use the PPC Toolbox if your application communicates with other applications using high-level events or Apple events, and your application allows the user to choose another application to communicate with. You can use a PPC Toolbox routine that provides a standard user interface to display a dialog box that lists other applications that are available to exchange information. See "Browsing for Ports Using the Program Linking Dialog Box" beginning on page 11-22 for detailed information. See the chapter "Event Manager" in Inside Macintosh: Macintosh Toolbox Essentials for information on high-level events, and see earlier chapters in this book for information on Apple events.

The PPC Toolbox uses the AppleTalk Data Stream Protocol (ADSP) and the Name-Binding Protocol (NBP). For detailed information on ADSP and NBP, see Inside Macintosh: Networking.

Note

The sample applications "store data," "display data," "send and receive," "make memo," and "spell quick" used in this chapter are not actual products of Apple Computer, Inc. They are used for illustrative purposes only.

---

Chapter Contents

About the PPC Toolbox

Ports, Sessions, and Message Blocks

Setting Up Authenticated Sessions

Using the PPC Toolbox

PPC Toolbox Calling Conventions

Specifying Port Names and Location Names

Opening a Port

Browsing for Ports Using the Program Linking Dialog Box

Obtaining a List of Available Ports

Preparing for a Session

Initiating a PPC Session

Receiving Session Requests

Accepting or Rejecting Session Requests

Exchanging Data During a PPC Session

Reading Data From an Application

Sending Data to an Application

Ending a Session and Closing a Port

Invalidating Users

PPC Toolbox Reference

Data Structures

The PPC Toolbox Parameter Block

The PPC Port Record

The Location Name Record

The Port Information Record

PPC Toolbox Routines

Initializing the PPC Toolbox

Using the Program Linking Dialog Box

Obtaining a List of Ports

Opening and Closing a Port

Starting and Ending a Session

Receiving, Accepting, and Rejecting a Session

Reading and Writing Data

Locating a Default User and Invalidating a User

Application-Defined Routines

Completion Routines for PPC Toolbox Routines

Port Filter Functions

Summary of the PPC Toolbox

Pascal Summary

Constants

Data Types

PPC Toolbox Routines

Initializing the PPC Toolbox

Using the Program Linking Dialog Box

Obtaining a List of Ports

Opening and Closing a Port

Starting and Ending a Session

Receiving, Accepting, and Rejecting a Session

Reading and Writing Data

Locating a Default User and Invalidating a User

Application-Defined Routines

C Summary

Constants

Data Types

PPC Toolbox Routines

Initializing the PPC Toolbox

Using the Program Linking Dialog Box

Obtaining a List of Ports

Opening and Closing a Port

Starting and Ending a Session

Receiving, Accepting, and Rejecting a Session

Reading and Writing Data

Locating a Default User and Invalidating a User

Application-Defined Routines

Assembly-Language Summary

Trap Macros

Trap Macros Requiring Routine Selectors

Result Codes