LayerPD_Layer
ObjectSmartPDPage

This class ensures that PDPage objects are released even in case of exceptions and RAISE.

There are many ways to acquire a Page that you need to be careful about, and those APIs are listed below:

Note that PDPage objects retrieved using AVPageViewGetPage() should not be released.

This class is modeled based on a SmartPointer class. It does not have a release() API, as there was a clash in the meaning of the API in the auto_ptr domain and the PD API domain.

This class is designed to be a Final class, and hence does not have a virtual destructor. Classes that need this functionality should encapsulate it using containment.



Variable Summary
 Variable
 m_pdPage ()
 m_pdPage ()
Method Summary
 Method
 
Destructor.
 
void AcquirePage(PDDoc pdDoc, ASInt32 nPageNum)
The PDPage object is released. It then acquires a new PDPage pointer using PDDocAcquirePage(). Modules using this class should never call PDDocAcquirePage() directly.
 
void AssignAndTakeOwnership(PDPage pdPage)
The old PDPage pointer contained within is released. It then takes ownership of the PDPage pointer passed in as parameter. The method does not increase the reference count of the passed in PDPage object. This method is used in scenarios where the Smart pointer needs to be constructed before the page object becomes available. It is also used with APIs like PDPageAcquireFromCosPage() that have already increased the reference count for the PDPage object but are not encapsulated by the class methods.
 
void AssignPage(PDPage pdPage)
Wrapper for PDPageAcquirePage(). This API assumes that there is no PDPage object.
 
void AssignPage(PDDoc pdDoc, ASInt32 nPageNum)
Wrapper for PDDocAcquirePage(). This API assumes that there is no PDPage object.
 
Constructor.
 
* CSmartPDPage(PDDoc pdDoc, ASInt32 nPageNum)
Constructor.
 
* CSmartPDPage(PDPage pdPage)
Constructor.
 
* CSmartPDPage(const CSmartPDPage& cAutoPage)
Copy Constructor.
 
This method releases ownership of the internal PDPage object. The caller will be responsible for releasing the PDPage object. The PDPage object contained within will be empty once this API is called, and hence should not be used.
 
CSmartPDPage& operator=(const CSmartPDPage& hRhs)
Assignment operator.
 
CSmartPDPage& operator=(const hRhs)
PDPage assignment operator.
 
PDPage operator.
 
void Reset()
Releases the PDPage object. In case the object is empty, this method does not do anything. The PDPage object will no longer be valid once this method is called, and hence should not be used.
 
void UnitTestSmartPDPage(PDPage pdPageOwnedByCaller, PDDoc pdDoc, ASInt32 nPageNum)


Variables Detail
m_pdPage 
Product availability: Acrobat
Platform availability:

Syntax

PDPage volatile m_pdPage;

File: SmartPDPage.h
Line: 307
m_pdPage 
Product availability: Acrobat
Platform availability:

Syntax

PDPage m_pdPage;

File: SmartPDPage.h
Line: 309


Method Detail
~CSmartPDPage()
Product availability: Acrobat
Platform availability:

Syntax

~CSmartPDPage()

Destructor.

If the PDPage object is not empty, then it releases the PDPage object. This method is not a virtual method, since the class is supposed to be a Final class.

Returns

File: SmartPDPage.h
Line: 125
AcquirePage() 
Product availability: Acrobat
Platform availability:

Syntax

void AcquirePage(PDDoc pdDoc, ASInt32 nPageNum)

The PDPage object is released. It then acquires a new PDPage pointer using PDDocAcquirePage(). Modules using this class should never call PDDocAcquirePage() directly.

In the case of an exception, the object will be set to the empty state.

Parameters

pdDoc
 
nPageNum


File: SmartPDPage.h
Line: 152
AssignAndTakeOwnership() 
Product availability: Acrobat
Platform availability:

Syntax

void AssignAndTakeOwnership(PDPage pdPage)

The old PDPage pointer contained within is released. It then takes ownership of the PDPage pointer passed in as parameter. The method does not increase the reference count of the passed in PDPage object. This method is used in scenarios where the Smart pointer needs to be constructed before the page object becomes available. It is also used with APIs like PDPageAcquireFromCosPage() that have already increased the reference count for the PDPage object but are not encapsulated by the class methods.

In the case of an exception, the object will be set to the empty state.

Parameters

pdPage


File: SmartPDPage.h
Line: 173
AssignPage() 
Product availability: Acrobat
Platform availability:

Syntax

void AssignPage(PDPage pdPage)

Wrapper for PDPageAcquirePage(). This API assumes that there is no PDPage object.

In the case of an exception, the object will be set to the empty state.

Parameters

pdPage


File: SmartPDPage.h
Line: 331
AssignPage() 
Product availability: Acrobat
Platform availability:

Syntax

void AssignPage(PDDoc pdDoc, ASInt32 nPageNum)

Wrapper for PDDocAcquirePage(). This API assumes that there is no PDPage object.

In the case of an exception, the object will be set to the empty state.

Parameters

pdDoc
 
nPageNum


File: SmartPDPage.h
Line: 353
CSmartPDPage() 
Product availability: Acrobat
Platform availability:

Syntax

CSmartPDPage()

Constructor.

This is the default constructor. It is used along with AssignAndTakeOwnership() or the AcquirePage() method.

Returns

File: SmartPDPage.h
Line: 67
CSmartPDPage() 
Product availability: Acrobat
Platform availability:

Syntax

CSmartPDPage(PDDoc pdDoc, ASInt32 nPageNum)

Constructor.

This is a constructor for the most common PDPage creation APIs. Modules using this class should never call the PDDocAcquirePage() directly.

Parameters

pdDoc
 
nPageNum

Returns

File: SmartPDPage.h
Line: 82
CSmartPDPage() 
Product availability: Acrobat
Platform availability:

Syntax

CSmartPDPage(PDPage pdPage)

Constructor.

This constructor takes a PDPage pointer as parameter. It increases the reference count of the object before taking ownership of the PDPage pointer passed in. It is to be used in cases where the PDPage pointer is acquired by APIs that do not increase the reference count (for example, AVPageViewGetPage()).

Parameters

pdPage

Returns

File: SmartPDPage.h
Line: 98
CSmartPDPage() 
Product availability: Acrobat
Platform availability:

Syntax

CSmartPDPage(const CSmartPDPage& cAutoPage)

Copy Constructor.

It increases the reference count of the contained PDPage object in case it is not NULL.

Parameters

cAutoPage

Returns

File: SmartPDPage.h
Line: 111
GiveOwnershipToCaller() 
Product availability: Acrobat
Platform availability:

Syntax

PDPage GiveOwnershipToCaller()

This method releases ownership of the internal PDPage object. The caller will be responsible for releasing the PDPage object. The PDPage object contained within will be empty once this API is called, and hence should not be used.

This does not raise exceptions.

Returns

File: SmartPDPage.h
Line: 232
operator=() 
Product availability: Acrobat
Platform availability:

Syntax

CSmartPDPage operator=(const CSmartPDPage& hRhs)

Assignment operator.

This copies the PDPage pointer contained within the CSmartPDPage object passed in as parameter. It increases the reference count in case the PDPage pointer contained within the passed in object is not NULL.

In the case of an exception, the object will be set to the empty state.

Parameters

hRhs

Returns

File: SmartPDPage.h
Line: 209
operator=() 
Product availability: Acrobat
Platform availability:

Syntax

CSmartPDPage operator=(const hRhs)

PDPage assignment operator.

There is no clear way to handle this operator. It could be used as AssignAndTakeOwnership() (the reference count is unchanged) or AcquirePage(), where the reference count is increased by 1. Hence we have made this private so that the unambiguous APIs are explicitly used.

Parameters

hRhs

Returns

File: SmartPDPage.h
Line: 320
operator PDPage() 
Product availability: Acrobat
Platform availability:

Syntax

operator PDPage()

PDPage operator.

This is an operator to access the PDPage pointer contained within. This gives access to the raw pointer within and hence should not be released. The lifetime of the PDPage pointer returned is bound to the CSmartPDPage object that returned it.

This does not raise exceptions.

Returns

File: SmartPDPage.h
Line: 193
Reset() 
Product availability: Acrobat
Platform availability:

Syntax

void Reset()

Releases the PDPage object. In case the object is empty, this method does not do anything. The PDPage object will no longer be valid once this method is called, and hence should not be used.

In the case of an exception, the object will be set to the empty state.


File: SmartPDPage.h
Line: 246
UnitTestSmartPDPage() 
Product availability: Acrobat
Platform availability:

Syntax

void UnitTestSmartPDPage(PDPage pdPageOwnedByCaller, PDDoc pdDoc, ASInt32 nPageNum)

Parameters

pdPageOwnedByCaller
 
pdDoc
 
nPageNum


File: SmartPDPage.h
Line: 262