Heap-on-Node implementation. More...

#include <heap.h>

Collaboration diagram for pstsdk::heap:

Public Member Functions
	heap (const node &n)
	Open a heap object on a node.

	heap (const node &n, alias_tag)
	Open a heap object on a node alias.

	heap (const node &n, byte client_sig)
	Open a heap object on the specified node, and validate the client sig.

	heap (const node &n, byte client_sig, alias_tag)
	Open a heap object on the specified node (alias), and validate the client sig.

	heap (const heap &other)
	Copy constructor.

	heap (const heap &other, alias_tag)
	Alias constructor.

	heap (heap &&other)
	Move constructor.

size_t	size (heap_id id) const
	Get the size of the given allocation.

heap_id	get_root_id () const
	Returns the client root allocation out of this heap.

byte	get_client_signature () const
	Returns the client signature of the heap.

size_t	read (std::vector< byte > &buffer, heap_id id, ulong offset) const
	Read data out of a specified allocation at the specified offset.

std::vector< byte >	read (heap_id id) const
	Read an entire allocation.

hid_stream_device	open_stream (heap_id id)
	Creates a stream device over a specified heap allocation.

const node &	get_node () const
	Get the node underlying this heap.

node &	get_node ()
	Get the node underlying this heap.

template<typename K , typename V >
std::shared_ptr< bth_node< K, V > >	open_bth (heap_id root)
	Opens a BTH from this heap with the given root id.

Detailed Description

Heap-on-Node implementation.

The HN is the first concept built on top of the node abstraction exposed by the NDB. It treats the node similar to how a memory heap is treated, allowing the client to allocate memory up to 3.8k and free those allocations from inside the node. To faciliate this, metadata is kept at the start and end of each block in the HN node (which are confusingly sometimes called pages in this context). So the HN has detailed knowledge of how blocks and extended_blocks work in order to do it's book keeping, and find the appropriate block (..page) to satisfy a given allocation request.

Note a heap completely controls a node - you can not have multiple heaps per node. You can not use a node which has a heap on it for any other purpose beyond the heap interface.

See also: [MS-PST 2.3.1]

Definition at line 194 of file heap.h.

Constructor & Destructor Documentation

◆ heap() [1/7]

pstsdk::heap::heap ( const node & n )

inlineexplicit

Open a heap object on a node.

Parameters

[in] n The node to open on top of. It will be copied.

Definition at line 199 of file heap.h.

◆ heap() [2/7]

pstsdk::heap::heap	(	const node &	n,
		alias_tag
	)

inline

Open a heap object on a node alias.

Parameters

[in] n The node to alias

Definition at line 203 of file heap.h.

◆ heap() [3/7]

pstsdk::heap::heap	(	const node &	n,
		byte	client_sig
	)

inline

Open a heap object on the specified node, and validate the client sig.

Exceptions

sig_mismatch If the specified client_sig doesn't match what is in the node

Parameters

[in]	n	The node to open on top of. It will be copied.
[in]	client_sig	Validate the heap has this value for the client sig

Definition at line 209 of file heap.h.

◆ heap() [4/7]

pstsdk::heap::heap	(	const node &	n,
		byte	client_sig,
		alias_tag
	)

inline

Open a heap object on the specified node (alias), and validate the client sig.

Exceptions

sig_mismatch If the specified client_sig doesn't match what is in the node

Parameters

[in]	n	The node to alias
[in]	client_sig	Validate the heap has this value for the client sig

Definition at line 215 of file heap.h.

◆ heap() [5/7]

pstsdk::heap::heap ( const heap & other )

inline

Copy constructor.

Parameters

[in] other The heap to copy

Definition at line 219 of file heap.h.

◆ heap() [6/7]

pstsdk::heap::heap	(	const heap &	other,
		alias_tag
	)

inline

Alias constructor.

Parameters

[in] other The heap to alias. The constructed object will share a heap_impl object with other.

Definition at line 223 of file heap.h.

◆ heap() [7/7]

pstsdk::heap::heap ( heap && other )

inline

Move constructor.

Parameters

[in] other The heap to move from

Definition at line 229 of file heap.h.

Member Function Documentation

◆ get_client_signature()

byte pstsdk::heap::get_client_signature ( ) const

inline

Returns the client signature of the heap.

Each heap is stamped with a signature byte by it's creator. This value is used mostly for validation purposes by the client when opening the heap.

See also: heap_client_signature returns The client sig byte

Definition at line 240 of file heap.h.

◆ get_node() [1/2]

node & pstsdk::heap::get_node ( )

inline

Get the node underlying this heap.

Returns: The node

Definition at line 256 of file heap.h.

◆ get_node() [2/2]

const node & pstsdk::heap::get_node ( ) const

inline

Get the node underlying this heap.

Returns: The node

Definition at line 253 of file heap.h.

◆ get_root_id()

heap_id pstsdk::heap::get_root_id ( ) const

inline

Returns the client root allocation out of this heap.

This value has specific meaning to the owner of the heap. It may point to a special structure which contains information about the data structures implemented in this heap or the larger node and subnodes (such as the table). Or, it could just point to the root BTH allocation (such as the property_bag). In any event, the heap itself gives no special meaning to this value.

Returns: The client's root allocation

Definition at line 237 of file heap.h.

◆ open_bth()

template<typename K , typename V >

std::shared_ptr< bth_node< K, V > > pstsdk::heap::open_bth ( heap_id root )

inline

Opens a BTH from this heap with the given root id.

Template Parameters

K	The key type of this BTH
V	The value type of this BTH

Parameters

[in] root The root allocation of this BTH

Returns: The BTH object

Definition at line 261 of file heap.h.

◆ open_stream()

hid_stream_device pstsdk::heap::open_stream ( heap_id id )

inline

Creates a stream device over a specified heap allocation.

The returned stream device can be used to construct a proper stream:

heap h;

hid_stream hstream(h.open_stream(0x30));

pstsdk::bth_nonleaf_node

Contains references to other bth_node allocations.

Definition heap.h:364

pstsdk::heap

Heap-on-Node implementation.

Definition heap.h:195

pstsdk::hid_stream

boost::iostreams::stream< hid_stream_device > hid_stream

The actual heap allocation stream, defined using the boost iostream library and the hid_stream_device...

Definition heap.h:79

Which can then be used as any iostream would be.

Parameters

[in] id The heap allocation to open a stream on

Returns: A heap allocation stream device

Definition at line 249 of file heap.h.

◆ read() [1/2]

std::vector< byte > pstsdk::heap::read ( heap_id id ) const

inline

Read an entire allocation.

Exceptions

length_error (PSTSDK_VALIDATION_LEVEL_WEAK) If the page or index of the allocation as indicated by the id are out of bounds for this node

Parameters

[in] id The allocation to read

Returns: The entire allocation

Definition at line 246 of file heap.h.

◆ read() [2/2]

size_t pstsdk::heap::read	(	std::vector< byte > &	buffer,
		heap_id	id,
		ulong	offset
	)		const

inline

Read data out of a specified allocation at the specified offset.

Exceptions

length_error (PSTSDK_VALIDATION_LEVEL_WEAK) If the page, index, or size of the allocation are out of bounds

Parameters

[in]	buffer	The location to store the data. The size of the buffer indicates the amount of data to read
[in]	id	The heap allocation to read from
[in]	offset	The offset into id to read starting at

Returns: The number of bytes read

Definition at line 243 of file heap.h.

◆ size()

size_t pstsdk::heap::size ( heap_id id ) const

inline

Get the size of the given allocation.

Parameters

[in] id The heap allocation to get the size of

Exceptions

length_error (PSTSDK_VALIDATION_LEVEL_WEAK) If the page or index of the allocation as indicated by the id are out of bounds for this node

Returns: The size of the allocation

Definition at line 234 of file heap.h.

The documentation for this class was generated from the following file:

pstsdk/ltp/heap.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ heap() [1/7]

◆ heap() [2/7]

◆ heap() [3/7]

◆ heap() [4/7]

◆ heap() [5/7]

◆ heap() [6/7]

◆ heap() [7/7]

Member Function Documentation

◆ get_client_signature()

◆ get_node() [1/2]

◆ get_node() [2/2]

◆ get_root_id()

◆ open_bth()

◆ open_stream()

◆ read() [1/2]

◆ read() [2/2]

◆ size()