Write Callbacks for Operators

When Quartz invokes your callback for a PDF operators, it passes a CGPDFScanner object and a pointer to any information needed by your callback. Typically, your callback retrieves any items associated with the operator. For example, the callback for the MP operator that’s shown in Listing 14-2 calls the function CGPDFScannerPopName to retrieve the character string associated with the operator from the stack. If the code in the listing successfully retrieves the name from the scanner stack, it prints the name.

Quartz has an assortment of CGPDFScannerPop functions for retrieving objects, Boolean values, names, numbers, strings, arrays, dictionaries, and streams. Each function returns a Boolean value to indicate whether the item was retrieved successfully.

Listing 14-2  A callback for the MP operator

static void

op_MP (CGPDFScannerRef s, void *info)

{

    const char *name;

    if (!CGPDFScannerPopName(s, &name))

        return;

    printf("MP /%s\n", name);

}

Create and Set Up the Operator Table

A CGPDFOperatorTable object stores PDF operator callback functions that you write. The function CGPDFOperatorTableCreate creates an operator table, as shown in Listing 14-3. After you create an operator table, you call the function CGPDFOperatorTableSetCallback for each callback you want to add to the table. You pass the table, the string that specifies the PDF operator, and a pointer to a callback function you write to handle that operator. You can name the callbacks whatever you’d like. Just make sure that the callback name you pass to the function CGPDFOperatorTableSetCallback isn’t misspelled.

The code in Listing 14-3 sets a callback for each of the marked-content operators listed in Table 14-1. Your application would set callbacks only for those operators of interest. PDF operator strings are defined in the PDF Reference from Adobe.

Listing 14-3  Setting callbacks for an operator table

CGPDFOperatorTableRef myTable;

myTable = CGPDFOperatorTableCreate();

CGPDFOperatorTableSetCallback (myTable, "MP", &op_MP);

CGPDFOperatorTableSetCallback (myTable, "DP", &op_DP);

CGPDFOperatorTableSetCallback (myTable, "BMC", &op_BMC);

CGPDFOperatorTableSetCallback (myTable, "BDC", &op_BDC);

CGPDFOperatorTableSetCallback (myTable, "EMC", &op_EMC);

Open the PDF Document

Before you can scan the content of a PDF document, you need to open it. Listing 14-4 shows a code fragment that creates a CGPDFDocument object from a URL supplied to the code. Note that the listing is a code fragment, so that not all variables are declared. A detailed explanation for each numbered line of code appears following the listing.

Listing 14-4  Opening a PDF document from a URL

CGPDFDocumentRef myDocument;

myDocument = CGPDFDocumentCreateWithURL(url);// 1

if (myDocument == NULL) {// 2

        error ("can't open `%s'.", filename);

        CFRelease (url);

        return EXIT_FAILURE;

}

CFRelease (url);

if (CGPDFDocumentIsEncrypted (myDocument)) {// 3

    if (!CGPDFDocumentUnlockWithPassword (myDocument, "")) {

        printf ("Enter password: ");

        fflush (stdout);

        password = fgets(buffer, sizeof(buffer), stdin);

        if (password != NULL) {

            buffer[strlen(buffer) - 1] = '\0';

            if (!CGPDFDocumentUnlockWithPassword (myDocument, password))

                error("invalid password.");

        }

    }

}

if (!CGPDFDocumentIsUnlocked (myDocument)) {// 4

        error("can't unlock `%s'.", filename);

        CGPDFDocumentRelease(myDocument);

        return EXIT_FAILURE;

    }

}

 if (CGPDFDocumentGetNumberOfPages(myDocument) == 0) {// 5

        CGPDFDocumentRelease(myDocument);

        return EXIT_FAILURE;

}

Here’s what the code does:

1. Creates a CGPDFDocument object from a URL supplied to the code.

2. Checks to make sure that a CGPDFDocument object is created. If not, the code exits because it makes no sense to continue without a document.

3. Checks whether the document is encrypted. If the document is encrypted, the code attempts to open is using a blank password. If that fails, the code asks the user for a password and attempts to unlock the document with the password.

4. Checks whether the document is unlocked. If it’s not, the code exits.

5. Checks to make sure the document has at least one page. Otherwise, the code exits.

Scan the Content Stream for Each Page

The code fragment in Listing 14-5 scans each page in a document. When the scanner encounters one of the PDF operators for which you registered a callback, Quartz invokes your callback. A detailed explanation for each numbered line of code follows the listing.

Listing 14-5  Scanning each page of a document

int k;

CGPDFPageRef myPage;

CGPDFScannerRef myScanner;

CGPDFContentStreamRef myContentStream;

numOfPages = CGPDFDocumentGetNumberOfPages (myDocument);// 1

for (k = 0; k < numOfPages; k++) {

    myPage = CGPDFDocumentGetPage (myDocument, k + 1 );// 2

    myContentStream = CGPDFContentStreamCreateWithPage (myPage);// 3

    myScanner = CGPDFScannerCreate (myContentStream, myTable, NULL);// 4

    CGPDFScannerScan (myScanner);// 5

    CGPDFPageRelease (myPage);// 6

    CGPDFScannerRelease (myScanner);// 7

    CGPDFContentStreamRelease (myContentStream);// 8

 }

 CGPDFOperatorTableRelease(myTable);// 9

Here’s what the code does:

1. Gets the number of pages in the document that you previously opened. See Open the PDF Document.

2. Retrieves a page to scan. The page numbers start at 1.

3. Creates a content stream for the page.

4. Creates a scanner for the content stream. You must pass the content stream and the operator table that you previously created and set with callbacks. See Create and Set Up the Operator Table. You can also pass any data that your callbacks need.

5. Parses the content stream associated with the scanner. Quartz invokes your callback each time it encounters one of the operators for which you provided a callback.

6. Releases the page.

7. Releases the scanner.

8. Releases the content stream.

9. Releases the operator table after scanning all the pages in the PDF.