|
| BUnarchiver (const BMessage *archive) |
| Constructs a BUnarchiver object to manage archive . More...
|
|
| ~BUnarchiver () |
| Destroys a BUnarchiver object. More...
|
|
const BMessage * | ArchiveMessage () const |
| Returns the BMessage* used to construct this BUnarchiver. More...
|
|
void | AssumeOwnership (BArchivable *archivable) |
| Become the owner of archivable. More...
|
|
status_t | EnsureUnarchived (const char *name, int32 index=0) |
| Ensure the object archived under name at index is unarchived and instantiated. More...
|
|
status_t | EnsureUnarchived (int32 token) |
| Ensure the object represented by token is unarchived and instantiated. More...
|
|
template<class T > |
status_t | FindObject (const char *name, T *&object) |
| Recover and take ownership of an object at index 0 that had previously been archived using the BArchiver::AddArchivable() method. More...
|
|
template<class T > |
status_t | FindObject (const char *name, ownership_policy owning, T *&object) |
| Recover an object at index 0 that had previously been archived using the BArchiver::AddArchivable() method. More...
|
|
template<class T > |
status_t | FindObject (const char *name, int32 index, T *&object) |
| Recover and take ownership of an object that had previously been archived using the BArchiver::AddArchivable() method. More...
|
|
template<class T > |
status_t | FindObject (const char *name, int32 index, ownership_policy owning, T *&object) |
| Recover an object that had previously been archived using the BArchiver::AddArchivable() method. More...
|
|
status_t | Finish (status_t err=B_OK) |
| Report any unarchiving errors and possibly complete the archiving session. More...
|
|
template<class T > |
status_t | GetObject (int32 token, T *&object) |
| Recover and take ownership of an object represented by token. More...
|
|
template<class T > |
status_t | GetObject (int32 token, ownership_policy owning, T *&object) |
| Recover an object by token that was archived by a BArchiver object. If the object has not yet been instantiated, and this request is not coming from an AllUnarchived() implementation, the object will be instantiated now. More...
|
|
bool | IsInstantiated (int32 token) |
| Checks whether the object represented by token has been instantiated in this session. More...
|
|
bool | IsInstantiated (const char *name, int32 index=0) |
| Checks whether the object archived under name at index has been instantiated in this session. More...
|
|
void | RelinquishOwnership (BArchivable *archivable) |
| Relinquish ownership of archivable. If archivable remains unclaimed at the end of the unarchiving session, it will be deleted (unless it is the root object). More...
|
|
A class that simplifies the unarchiving of complicated BArchivable hierarchies.
The BUnarchiver class is a small class used to recover BArchivable objects that have been archived with the BArchiver class. It also provides ownership semantics, so that memory leaks can be avoided during the unarchival process. When retrieving an object (either via GetObject() or FindObject()), you can specify a BUnarchiver::ownership_policy. If you specify BUnarchiver::B_ASSUME_OWNERSHIP, you will become responsible for deleting the retrieved item. If you specify BUnarchiver::B_DONT_ASSUME_OWNERSHIP, you will not become responsible. You cannot take ownership of the same object twice. After the unarchival process finishes, any unclaimed objects, excluding the root object (the object being instantiated via instantiate_object() or BUnarchiver::InstantiateObject()), will be deleted.
If you are updating a class that previously did not use the BArchiver and BUnarchiver helper classes, and want to maintain backwards compatibility with old archive, this can be done using the IsArchiveManaged() method.
- Warning
- Calling methods on your BUnarchiver with a legacy archive (one that was not managed by a BArchiver during archival) will result in a call to debugger().
- Since
- Haiku R1
Recover an object that had previously been archived using the BArchiver::AddArchivable() method.
If the object has not yet been instantiated, and this request is not coming from an AllUnarchived() implementation, the object will be instantiated now.
If the retrieved object is not of the type T, then this method will fail. If this method fails, you will not receive ownership of the object, no matter what you specified in owning
.
- Template Parameters
-
T | The type of object you wish to find. |
- Parameters
-
name | The name that was passed to BArchiver::AddArchivable() when adding this object. |
index | The index of the object you wish to recover (0-based , like BMessage::FindData(). |
owning | Dictates whether or not you wish to take ownership of the retrieved object. |
object | Return parameter for the retrieved object of type T. |
- Returns
- A status code.
- Return values
-
B_OK | The object retrieved was of type T. |
B_BAD_TYPE | The object retrieved was not of type T. |
- Since
- Haiku R1
References NULL.
Report any unarchiving errors and possibly complete the archiving session.
This method may finish an unarchiving session (triggering the call of all instantiated objects' AllUnarchived() methods) if the following conditions are true:
- No errors have been reported to this or any other BUnarchiver object within this session.
- This is the last remaining BUnarchiver that has not had its Finish() method invoked.
If you call this method with an error code not equal to B_OK, then this unarchiving session has failed, instantiated objects will not have their AllUnarchived() methods called, and any subsequent calls to this method on any BUnarchiver objects in this session will return your error code. Furthermore, any objects that have been instantiated, but have not had their ownership assumed by another object will now be deleted (excluding the root object).
- Returns
- The first error reported in this unarchiving session, or
B_OK
.
- Since
- Haiku R1
Recover an object by token that was archived by a BArchiver object. If the object has not yet been instantiated, and this request is not coming from an AllUnarchived() implementation, the object will be instantiated now.
If the retrieved object is not of the type T, then this method will fail. If this method fails, you will not receive ownership of the object, no matter what you specified in owning
.
- Template Parameters
-
T | The type of object you wish to find. |
- Parameters
-
token | The token you got for this object from BArchiver::GetTokenForArchivable() during archival. |
owning | Whether or not you wish to take ownership of the retrieved object. |
object | Return parameter for the retrieved object of type T. |
- Returns
- A status code.
- Return values
-
B_OK | The object retrieved was of type T. |
B_BAD_TYPE | The object retrieved was not of type T. |
- Since
- Haiku R1
References NULL.