commit c5169371aab898b7e9f928bfccc40adbe07a314a
author Lei Zhang <thestig@chromium.org> Tue Apr 13 23:32:28 2021 +0000
committer Chromium commit bot <commit-bot@chromium.org> Tue Apr 13 23:32:28 2021 +0000
tree 5935a5bec6c9f9c6c39bdf0c1a8d5cb8168d79c6
parent f9418b58ed0740a467ac108e153a26f24fbe831a

Clarify FPDF_ACTION lifetimes.

FPDF_ACTION cannot outlive the object that contains it. Make a note of
this in the functions that return FPDF_ACTION.

Change-Id: I1b206f149f5257dc3a87c44149ff4342dfbc364f
Reviewed-on: https://pdfium-review.googlesource.com/c/pdfium/+/79300
Commit-Queue: Lei Zhang <thestig@chromium.org>
Reviewed-by: Tom Sepez <tsepez@chromium.org>

public/fpdf_doc.h

diff --git a/public/fpdf_doc.h b/public/fpdf_doc.h
index 3a17c01..3572cb1 100644
--- a/public/fpdf_doc.h
+++ b/public/fpdf_doc.h
@@ -112,7 +112,7 @@
 //   document - handle to the document.
 //   bookmark - handle to the bookmark.
 //
-// Returns the handle to the destination data,  NULL if no destination is
+// Returns the handle to the destination data, or NULL if no destination is
 // associated with |bookmark|.
 FPDF_EXPORT FPDF_DEST FPDF_CALLCONV
 FPDFBookmark_GetDest(FPDF_DOCUMENT document, FPDF_BOOKMARK bookmark);
@@ -122,8 +122,11 @@
 //   bookmark - handle to the bookmark.
 //
 // Returns the handle to the action data, or NULL if no action is associated
-// with |bookmark|. When NULL is returned, FPDFBookmark_GetDest() should be
-// called to get the |bookmark| destination data.
+// with |bookmark|.
+// If this function returns a valid handle, it is valid as long as |bookmark| is
+// valid.
+// If this function returns NULL, FPDFBookmark_GetDest() should be called to get
+// the |bookmark| destination data.
 FPDF_EXPORT FPDF_ACTION FPDF_CALLCONV
 FPDFBookmark_GetAction(FPDF_BOOKMARK bookmark);
 
@@ -279,6 +282,8 @@
 //   link - handle to the link.
 //
 // Returns a handle to the action associated to |link|, or NULL if no action.
+// If this function returns a valid handle, it is valid as long as |link| is
+// valid.
 FPDF_EXPORT FPDF_ACTION FPDF_CALLCONV FPDFLink_GetAction(FPDF_LINK link);
 
 // Enumerates all the link annotations in |page|.
@@ -341,6 +346,8 @@
 //
 //   Returns the handle to the action data, or NULL if there is no
 //   additional-action of type |aa_type|.
+//   If this function returns a valid handle, it is valid as long as |page| is
+//   valid.
 FPDF_EXPORT FPDF_ACTION FPDF_CALLCONV FPDF_GetPageAAction(FPDF_PAGE page,
                                                           int aa_type);