Sets of independent objects and repository rows are divided into pages; each page is a number of collection elements (objects or rows) that represent a subset of the collection elements. You can enumerate a page at a time instead of one object or row at a time. As an example, if a page is defined as 10 elements, and the collection has a total of 22 elements, the first paging operation returns a page containing 10 elements, the second page returns the next 10 elements, and the third page returns the last 2 elements. This page enumeration is especially useful for interactive applications that display a page of information at a time.
Each page enumerator is initially positioned before the first page of the set. The first call to the
method moves the enumerator to the first page. The second call to
moves the enumerator to the second page, and so on. The
method returns
until the end of the set is
reached. When the enumerator reaches the end of the set, it is positioned after the last page and
returns
.
The
and
methods throw an exception if the enumerator is positioned before the first page or after the last page, or between pages after a
operation. For proper positioning, you must call
on a new enumerator and after a
operation. You may call the
method at any time. Of these methods, only
moves the position of the enumerator.
The returned value of
is always equal to
. Use
to avoid copying the potentially large internal array just to get its length.
You can also get the current page continuation state (that is, the page on which the enumerator will continue with the next call) and reset the enumerator back to a previous page of results. The saved position of the enumerator is called a "page mark". The
method retrieves the current mark, and the
method resets the state of the enumerator to a previously saved mark. The
method positions the enumerator before the marked page; the
method must be called to position the enumerator to the marked page. It is also possible to mark and reset to the position before the first page and the position after the last page.
The
(with no parameters) positions the enumerator before the first page of the collection. This is essentially the same as getting a new enumerator from the collection. You must then call the
method to position the enumerator to the first page.
The
and
methods allow you to query and adjust the internal paging size of the enumerator. The new size takes effect on the next fetch from the server. This is typically on the next call to
. The actual size of each returned page may be smaller (including zero) or larger than the requested page size.
The first page of a set may be pre-fetched from the server and cached in the client. All enumerators of a set with a pre-fetched first page may return the same first page. All enumerators fetch subsequent pages, if any, directly from the server.
The following tables list the members exposed by IPageEnumerator.
Public Properties
Name | Description | |
---|---|---|
![]() | CurrentPage | Returns the current page in the set. |
![]() | ElementCount | Returns the number of elements in the current page. The returned value is always equal to the value returned by . Use to avoid copying the potentially large internal array just to get its length. |
![]() | PageMark | Returns the current page mark on which a subsequent call to will operate. Call this method before calling the method. |
![]() | PageSize | The internal paging size used by the enumerator. GetPageSize returns the internal paging size used by the enumerator. SetPageSize sets the internal paging size used by the enumerator. The new size takes effect on the next fetch from the server. Typical use cases for changing the page size are to match the number of displayed elements in a user interface or to improve performance of page retrieval. |
Public Methods
Name | Description | |
---|---|---|
![]() | NextPage | Moves the enumerator to the first page in the set on the first call and to the next page in the set on subsequent calls. |
![]() | Reset | Overloaded. Positions the enumerator to a point before the first page of the collection. You must call to position the enumerator to the first page. |