FCbPackage Class Reference

#include <CompactBinaryPackage.h>

Public Types
using	FAttachmentResolver = TFunctionRef< FSharedBuffer(const FIoHash &Hash)>

Public Member Functions
	FCbPackage ()=default
	FCbPackage (FCbObject InObject)
	FCbPackage (FCbObject InObject, FAttachmentResolver InResolver)
	FCbPackage (FCbObject InObject, const FIoHash &InObjectHash)
	FCbPackage (FCbObject InObject, const FIoHash &InObjectHash, FAttachmentResolver InResolver)
void	Reset ()
	operator bool () const
bool	IsNull () const
const FCbObject &	GetObject () const
const FIoHash &	GetObjectHash () const
void	SetObject (FCbObject InObject)
void	SetObject (FCbObject InObject, FAttachmentResolver InResolver)
void	SetObject (FCbObject InObject, const FIoHash &InObjectHash)
void	SetObject (FCbObject InObject, const FIoHash &InObjectHash, FAttachmentResolver InResolver)
TConstArrayView< FCbAttachment >	GetAttachments () const
CORE_API const FCbAttachment *	FindAttachment (const FIoHash &Hash) const
const FCbAttachment *	FindAttachment (const FCbAttachment &Attachment) const
void	AddAttachment (const FCbAttachment &Attachment)
void	AddAttachment (const FCbAttachment &Attachment, FAttachmentResolver Resolver)
CORE_API int32	RemoveAttachment (const FIoHash &Hash)
int32	RemoveAttachment (const FCbAttachment &Attachment)
CORE_API bool	Equals (const FCbPackage &Package) const
bool	operator== (const FCbPackage &Package) const
bool	operator!= (const FCbPackage &Package) const
CORE_API bool	TryLoad (FCbFieldIterator &Fields)
CORE_API bool	TryLoad (FArchive &Ar, FCbBufferAllocator Allocator=FUniqueBuffer::Alloc)
CORE_API void	Save (FCbWriter &Writer) const
CORE_API void	Save (FArchive &Ar) const

Detailed Description

A package is an object with a tree of referenced attachments.

A package is a Merkle tree with an object as its root and non-leaf nodes, and either binary or objects as its leaf nodes. Nodes reference their children from fields of type BinaryAttachment or ObjectAttachment, which store the raw hash of the referenced attachment.

It is invalid for a package to include attachments that are not referenced by its object or by one of its referenced object attachments. This invariant needs to be maintained if attachments are added explicitly instead of being discovered by the attachment resolver. If any attachment is not referenced, it may not survive a round-trip through certain storage systems.

It is valid for a package to exclude referenced attachments, but then it is the responsibility of the package consumer to have a mechanism for resolving those references when necessary.

A package is serialized as a sequence of compact binary fields with no name. The object may be both preceded and followed by attachments. The object is only serialized when it is non-empty, starting with its hash, in a Hash field, followed by the object, in an Object field. A package ends with a Null field. The canonical order of components is the object and its hash, followed by the attachments ordered by hash, followed by a Null field. It is valid for the a package to have its attachments serialized in any order relative to each other and to the object.

Member Typedef Documentation

FAttachmentResolver

using FCbPackage::FAttachmentResolver = TFunctionRef<FSharedBuffer (const FIoHash& Hash)>

A function that resolves a hash to a buffer containing the data matching that hash.

The resolver may return a null buffer to skip resolving an attachment for the hash.

Constructor & Destructor Documentation

FCbPackage() [1/5]

FCbPackage::FCbPackage ( )

default

Construct a null package.

FCbPackage() [2/5]

FCbPackage::FCbPackage ( FCbObject  InObject )

inlineexplicit

Construct a package from a root object without gathering attachments.

Parameters

InObject

The root object, which will be cloned unless it is owned.

FCbPackage() [3/5]

FCbPackage::FCbPackage ( FCbObject  InObject, FAttachmentResolver  InResolver  )

inlineexplicit

Construct a package from a root object and gather attachments using the resolver.

Parameters

InObject	The root object, which will be cloned unless it is owned.
InResolver	A function that is invoked for every reference and binary reference field.

FCbPackage() [4/5]

FCbPackage::FCbPackage ( FCbObject  InObject, const FIoHash &  InObjectHash  )

inlineexplicit

Construct a package from a root object without gathering attachments.

Parameters

InObject	The root object, which will be cloned unless it is owned.
InObjectHash	The hash of the object, which must match to avoid validation errors.

FCbPackage() [5/5]

FCbPackage::FCbPackage ( FCbObject  InObject, const FIoHash &  InObjectHash, FAttachmentResolver  InResolver  )

inlineexplicit

Construct a package from a root object and gather attachments using the resolver.

Parameters

InObject	The root object, which will be cloned unless it is owned.
InObjectHash	The hash of the object, which must match to avoid validation errors.
InResolver	A function that is invoked for every reference and binary reference field.

Member Function Documentation

AddAttachment() [1/2]

void FCbPackage::AddAttachment ( const FCbAttachment &  Attachment )

inline

Add the attachment to this package.

AddAttachment() [2/2]

void FCbPackage::AddAttachment ( const FCbAttachment &  Attachment, FAttachmentResolver  Resolver  )

inline

Add the attachment to this package, along with any references that can be resolved.

Equals()

bool FCbPackage::Equals

(

const FCbPackage &

Package

)

const

Compares packages by their object and attachment hashes.

FindAttachment() [1/2]

const FCbAttachment * FCbPackage::FindAttachment ( const FCbAttachment &  Attachment ) const

inline

Find an attachment if it exists in the package.

FindAttachment() [2/2]

const FCbAttachment * FCbPackage::FindAttachment

(

const FIoHash &

Hash

)

const

Find an attachment by its hash.

Returns

The attachment, or null if the attachment is not found.

Note

The returned pointer is only valid until the attachments on this package are modified.

GetAttachments()

TConstArrayView< FCbAttachment > FCbPackage::GetAttachments ( ) const

inline

Returns the attachments in this package.

GetObject()

const FCbObject & FCbPackage::GetObject ( ) const

inline

Returns the object for the package.

GetObjectHash()

const FIoHash & FCbPackage::GetObjectHash ( ) const

inline

Returns the hash of the object for the package.

IsNull()

bool FCbPackage::IsNull ( ) const

inline

Whether the package has an empty object and no attachments.

operator bool()

FCbPackage::operator bool ( ) const

inlineexplicit

Whether the package has a non-empty object or attachments.

operator!=()

bool FCbPackage::operator!= ( const FCbPackage &  Package ) const

inline

operator==()

bool FCbPackage::operator== ( const FCbPackage &  Package ) const

inline

RemoveAttachment() [1/2]

int32 FCbPackage::RemoveAttachment ( const FCbAttachment &  Attachment )

inline

RemoveAttachment() [2/2]

int32 FCbPackage::RemoveAttachment

(

const FIoHash &

Hash

)

Remove an attachment by hash.

Returns

Number of attachments removed, which will be either 0 or 1.

Reset()

void FCbPackage::Reset ( )

inline

Reset this to a null package.

Save() [1/2]

void FCbPackage::Save

(

FArchive &

Ar

)

const

Save the object and attachments into the archive as a stream of compact binary fields.

Save() [2/2]

void FCbPackage::Save

(

FCbWriter &

Writer

)

const

Save the object and attachments into the writer as a stream of compact binary fields.

SetObject() [1/4]

void FCbPackage::SetObject ( FCbObject  InObject )

inline

Set the root object without gathering attachments.

Parameters

InObject

The root object, which will be cloned unless it is owned.

SetObject() [2/4]

void FCbPackage::SetObject ( FCbObject  InObject, const FIoHash &  InObjectHash  )

inline

Set the root object without gathering attachments.

Parameters

InObject	The root object, which will be cloned unless it is owned.
InObjectHash	The hash of the object, which must match to avoid validation errors.

SetObject() [3/4]

void FCbPackage::SetObject ( FCbObject  InObject, const FIoHash &  InObjectHash, FAttachmentResolver  InResolver  )

inline

Set the root object and gather attachments using the resolver.

Parameters

InObject	The root object, which will be cloned unless it is owned.
InObjectHash	The hash of the object, which must match to avoid validation errors.
InResolver	A function that is invoked for every reference and binary reference field.

SetObject() [4/4]

void FCbPackage::SetObject ( FCbObject  InObject, FAttachmentResolver  InResolver  )

inline

Set the root object and gather attachments using the resolver.

Parameters

InObject	The root object, which will be cloned unless it is owned.
InResolver	A function that is invoked for every reference and binary reference field.

TryLoad() [1/2]

bool FCbPackage::TryLoad	(	FArchive &	Ar,
		FCbBufferAllocator	Allocator = FUniqueBuffer::Alloc
	)

Load the object and attachments from compact binary as written by Save.

The object and attachments will be individually loaded into owned buffers.

Parameters

Ar	Archive to read the package from. An error state is set on failure.
Allocator	Allocator for object and attachment buffers.

Note

Allocated buffers will be cloned if they are not owned.

TryLoad() [2/2]

bool FCbPackage::TryLoad

(

FCbFieldIterator &

Fields

)

Load the object and attachments from compact binary as written by Save.

The object and attachments reference the input iterator, if it is owned, and otherwise clones the object and attachments individually to make owned copies.

The iterator is advanced as object and attachment fields are consumed from it.

---

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

• Engine/Source/Runtime/Core/Public/Serialization/CompactBinaryPackage.h
• Engine/Source/Runtime/Core/Private/Serialization/CompactBinaryPackage.cpp