How does the PDF Library work with a document's OutputIntent?

The OutputIntents is an optional entry in the document catalog, or root dictionary. It is an array of OutputIntent dictionaries that describe the color reproduction characteristics of possible output devices. The purpose of an output intent is to allow you to associate one or more color profiles with a PDF document, so that the function sending a PDF to an output device (such as a printer) can select the appropriate profile to use. The OutputIntents array in a PDF document can define more than one color profile for that document.

See Section 14.11.5, “Output Intents,” in the ISO 32000 Reference.

If the target document does not have an output intent, you can build your Adobe PDF Library application to copy it from a source document:

CosObj inRoot = CosDocGetRoot (PDDocGetCosDoc (pddoc));
  CosDoc outCosDoc = PDDocGetCosDoc (newDocument);
  CosObj outRoot = CosDocGetRoot (outCosDoc);
  CosObj OIEntry = CosDictGetKeyString (inRoot, "OutputIntents");
  if (CosObjGetType (OIEntry) != CosNull)
  {
      /* If the source PDF has an OI entry, copy if over to the target PDF */
      CosDictPutKeyString (outRoot, "OutputIntents", CosObjCopy (OIEntry, outCosDoc, true));
  }

When rasterizing a page to a bitmap, if the Output Intent flag is set to true via the PDPrefUseOutputIntents() API, APDFL will use the output intent (matching the target colorspace components), overriding the default output profile and the profile specified in PDPageDrawContentsWithParams(), if any. If the Output Intent flag is false, APDFL will continue to use the output intent if the PDF document identifies as PDF/X, PDF/A or PDF/E compliant. An application can force the output intent to never be used with the PDPrefSetNeverUseOutputIntent() API.