FlmRecord Class Reference

Class for creating and modifying database records. More...

#include <flaim.h>

List of all members.

Public Member Functions

void * operator new (FLMSIZET uiSize) throw ()
 Overloaded new operator for FlmRecord objects.
void * operator new (FLMSIZET uiSize, const char *pszFile, int iLine) throw ()
 Overloaded new operator for ::FlmRecord objects (with source file and line number).
void * operator new[] (FLMSIZET uiSize) throw ()
 Overloaded new operator (array) for FlmRecord objects.
void * operator new[] (FLMSIZET uiSize, const char *pszFile, int iLine) throw ()
 Overloaded new operator (array) for FlmRecord objects (with source file and line number).
void operator delete (void *ptr)
 Overloaded delete operator for FlmRecord objects. Pointer to FlmRecord object being freed.
void operator delete[] (void *ptr)
 Overloaded delete operator (array) for FlmRecord objects. Pointer to array of FlmRecord objects being freed.
FLMINT FLMAPI AddRef (void)
 Increment the reference count for this FlmRecord object.
FINLINE FLMINT FLMAPI Release (void)
 Decrement the reference count for this FlmRecord object.
FlmRecordcopy (void)
 Make a writeable copy of this FlmRecord object.
RCODE clear (FLMBOOL bReleaseMemory=FALSE)
 Clear all fields in this FlmRecord object.
RCODE getINT (void *pvField, FLMINT *piNumber)
 Get a field's value as a FLMINT. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.
RCODE getINT32 (void *pvField, FLMINT32 *pi32Number)
 Get a field's value as a FLMINT32. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.
RCODE getINT64 (void *pvField, FLMINT64 *pi64Number)
 Get a field's value as a FLMINT64. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.
RCODE getUINT (void *pvField, FLMUINT *puiNumber)
 Get a field's value as a FLMUINT. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.
RCODE getUINT32 (void *pvField, FLMUINT32 *pui32Number)
 Get a field's value as a FLMUINT32. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.
RCODE getUINT64 (void *pvField, FLMUINT64 *pui64Number)
 Get a field's value as a FLMUINT64. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.
FINLINE RCODE getUnicodeLength (void *pvField, FLMUINT *puiLength)
 Get the number of bytes needed to retrieve a field's value as a unicode string.
RCODE getUnicode (void *pvField, FLMUNICODE *puzStrBuf, FLMUINT *puiStrBufLen)
 Get a field's value as a unicode string. Note that the field may be a FLM_NUMBER_TYPE, or FLM_TEXT_TYPE.
FINLINE RCODE getNativeLength (void *pvField, FLMUINT *puiLength)
 Get the number of bytes needed to retrieve a field's value as a native string.
RCODE getNative (void *pvField, char *pszStrBuf, FLMUINT *puiStrBufLen)
 Get a field's value as a native string. Note that the field may be a FLM_NUMBER_TYPE, or FLM_TEXT_TYPE.
FINLINE RCODE getBinaryLength (void *pvField, FLMUINT *puiLength)
 Get the number of bytes needed to retrieve a field's value as binary data.
RCODE getRecPointer (void *pvField, FLMUINT *puiRecPointer)
 Get the value for a FLM_CONTEXT_TYPE field as a FLMUINT.
FINLINE RCODE getRecPointer32 (void *pvField, FLMUINT32 *pui32RecPointer)
 Get the value for a FLM_CONTEXT_TYPE field as a FLMUINT32.
RCODE getBinary (void *pvField, void *pvBuf, FLMUINT *puiBufLen)
 Get a field's value as binary data.
RCODE getBlob (void *pvField, FlmBlob **ppBlob)
 Get a field's value as a FlmBlob object. This method may only be used on field's whose data type is FLM_BLOB_TYPE.
RCODE setINT (void *pvField, FLMINT iNumber, FLMUINT uiEncId=0)
 Set a field's value to a FLMINT value. The resulting data type for the field will be FLM_NUMBER_TYPE.
RCODE setINT64 (void *pvField, FLMINT64 i64Number, FLMUINT uiEncId=0)
 Set a field's value to a FLMINT64 value. The resulting data type for the field will be FLM_NUMBER_TYPE.
RCODE setUINT (void *pvField, FLMUINT uiNumber, FLMUINT uiEncId=0)
 Set a field's value to a FLMUINT value. The resulting data type for the field will be FLM_NUMBER_TYPE.
RCODE setUINT64 (void *pvField, FLMUINT64 ui64Number, FLMUINT uiEncId=0)
 Set a field's value to a FLMUINT64 value. The resulting data type for the field will be FLM_NUMBER_TYPE.
RCODE setRecPointer (void *pvField, FLMUINT uiRecPointer, FLMUINT uiEncId=0)
 Set a field's value to a FLMUINT value. The resulting data type for the field will be FLM_CONTEXT_TYPE.
RCODE setUnicode (void *pvField, const FLMUNICODE *puzUnicode, FLMUINT uiEncId=0)
 Set a field's value to a Unicode string value. The resulting data type for the field will be FLM_TEXT_TYPE.
RCODE setNative (void *pvField, const char *pszString, FLMUINT uiEncId=0)
 Set a field's value to a native string value. The resulting data type for the field will be FLM_TEXT_TYPE.
RCODE setBinary (void *pvField, const void *pvBuf, FLMUINT uiBufLen, FLMUINT uiEncId=0)
 Set a field's value to a binary value. The resulting data type for the field will be FLM_BINARY_TYPE.
RCODE setBlob (void *pvField, FlmBlob *pBlob, FLMUINT uiEncId=0)
 Set a field's value to a BLOB value. The resulting data type for the field will be FLM_BLOB_TYPE.
RCODE insert (void *pvField, FLMUINT uiInsertAt, FLMUINT uiFieldID, FLMUINT uiDataType, void **ppvField)
 Insert a new field into the FlmRecord object. Insertion is relative to an already existing field.
RCODE insertLast (FLMUINT uiLevel, FLMUINT uiFieldID, FLMUINT uiDataType, void **ppvField)
 Insert a new field into the FlmRecord object.
FINLINE RCODE remove (void *pvField)
 Remove a field from a record. The field and all of its descendant fields will be removed from the record.
FINLINE void * root (void)
 Return the root field of a record. The root field is the field that is at level zero in the record.
FINLINE void * nextSibling (void *pvField)
 Return the next sibling field of a field. Returns NULL if there is no next sibling field.
void * prevSibling (void *pvField)
 Return the previous sibling field of a field. Returns NULL if there is no previous sibling field.
FINLINE void * firstChild (void *pvField)
 Return the first child field of a field. Returns NULL if field has no child fields.
FINLINE void * lastChild (void *pvField)
 Return the last child field of a field. Returns NULL if field has no child fields.
FINLINE void * parent (void *pvField)
 Return the parent field of a field. Returns NULL if the field is the "root" field of the record.
FINLINE void * next (void *pvField)
 Return the "next" field of a field.
FINLINE void * prev (void *pvField)
 Return the "previous" field of a field.
void * find (void *pvStartField, FLMUINT uiFieldID, FLMUINT uiOccur=1, FLMUINT uiFindOption=SEARCH_FOREST)
 Find a field in a record that has a particular field number. Search is conducted relative to some other field in the record.
void * find (void *pvStartField, FLMUINT *puiFieldPath, FLMUINT uiOccur=1, FLMUINT uiFindOption=SEARCH_FOREST)
 Find a field in a record that has a particular field path. Search is conducted relative to some other field in the record.
FINLINE FLMUINT getLevel (void *pvField)
 Get the nesting level of a field in the record.
FINLINE FLMUINT getFieldID (void *pvField)
 Get the field number for a field.
FINLINE void setFieldID (void *pvField, FLMUINT uiFieldID)
 Set the field number for a field.
FINLINE FLMUINT getDataType (void *pvField)
 Get a field's data type.
FINLINE FLMUINT getDataLength (void *pvField)
 Get a field's data length. NOTE: This is the field's internal storage length.
FINLINE FLMBOOL hasChild (void *pvField)
 Determine if a field has any child fields.
FINLINE FLMBOOL isLast (void *pvField)
 Determine if a field has a next sibling field.
FINLINE void setRightTruncated (void *pvField, FLMBOOL bTrueFalse)
 Set a flag for a field indicating if its value has been "right truncated." Right truncation really only applies to binary data or strings.
FINLINE FLMBOOL isRightTruncated (void *pvField)
 Determine if field is marked as "right truncated." This really only applies to binary data or strings.
FINLINE void setLeftTruncated (void *pvField, FLMBOOL bTrueFalse)
 Set a flag for a field indicating if its value has been "left truncated." Left truncation really only applies to binary data or strings.
FINLINE FLMBOOL isLeftTruncated (void *pvField)
 Determine if field is marked as "left truncated." This really only applies to binary data or strings.
FINLINE RCODE getFieldInfo (void *pvField, FLMUINT *puiFieldNum, FLMUINT *puiLevel, FLMUINT *puiDataType, FLMUINT *puiLength, FLMUINT *puiEncLength, FLMUINT *puiEncId)
 Get information about a field.
FLMUINT getTotalMemory (void)
 Get the total memory being consumed by this FlmRecord object.
FINLINE FLMUINT getFreeMemory (void)
 Get the amount of memory allocated to the FlmRecord object that is currently not used.
RCODE compressMemory (void)
 Compress out unused memory within the FlmRecord object. See also FlmRecord::getFreeMemory().
FINLINE FLMUINT getID (void)
 Get the record ID (DRN) for this FlmRecord object.
FINLINE void setID (FLMUINT uiRecordID)
 Set the record ID (DRN) for this FlmRecord object.
FINLINE FLMUINT getContainerID (void)
 Get the container this FlmRecord object belongs to.
FINLINE void setContainerID (FLMUINT uiContainerID)
 Set the container this FlmRecord object belongs to.
RCODE importRecord (IF_FileHdl *pFileHdl, F_NameTable *pNameTable)
 Import a record from a file.
RCODE importRecord (const char **ppszBuffer, FLMUINT uiBufSize, F_NameTable *pNameTable)
 Import a record from a string buffer.
RCODE importRecord (NODE *pNode)
 Import a record from a Gedcom NODE tree.
RCODE exportRecord (HFDB hDb, F_Pool *pPool, NODE **ppNode)
 Export a record to a Gedcom NODE tree.
FINLINE FLMBOOL isReadOnly (void)
 Determine if the FlmRecord object is read-only.
FINLINE FLMBOOL isCached (void)
 Determine if the FlmRecord object is cached in FLAIM's record cache.
FINLINE FLMBOOL isOldVersion (void)
 Determine if the FlmRecord object is a prior version of the record or if it is the current version.
FINLINE const FLMBYTE * getDataPtr (void *pvField)
 Get a pointer to a field's data.
FINLINE FLMBOOL isEncryptedField (void *pvField)
 Determine if a field is encrypted.
FINLINE const FLMBYTE * getEncryptionDataPtr (void *pvField)
 Get a pointer to a field's encrypted data.
FINLINE FLMUINT getEncryptedDataLength (void *pvField)
 Get a field's encrypted data length.
FLMUINT getEncryptionID (void *pvField)
 Get a field's encryption id.
FLMUINT getEncFlags (void *pvField)
 Get a field's encryption flags.
FINLINE FLMBOOL fieldIdTableEnabled (void)
 Determine if a record has a level one field ID table.
FINLINE void enableFieldIdTable (void)
 Set a flag in the record that will cause it to generate a level one field ID table.
RCODE createFieldIdTable (FLMBOOL bTruncateTable)
 Create a level one field ID table in a record.
void * findLevelOneField (FLMUINT uiFieldID, FLMBOOL bFindInclusive, FLMUINT *puiFieldPos)
 Find a level one field ID in a record.
void * getLevelOneField (FLMUINT uiFieldId, FLMUINT uiLevelOnePosition)
 Determine if the level one field at the specified position in the field ID table matches the passed in field ID. If so, return that field pointer.
void * nextLevelOneField (FLMUINT *puiFieldPos, FLMBOOL bFieldIdsMustMatch)
 Get the next level one field after the position specified. Make sure that the next field has the same field ID as the current field.
FLMUINT getLevelOneFieldId (FLMUINT uiLevelOnePosition)
 Get the field ID of the field that is in the specified position in the field ID table.


Detailed Description

Class for creating and modifying database records.


Member Function Documentation

FLMINT FLMAPI FlmRecord::AddRef void   ) 
 

Increment the reference count for this FlmRecord object.

The reference count is the number of pointers that are referencing this FlmRecord object. Return value is the incremented reference count.

RCODE FlmRecord::clear FLMBOOL  bReleaseMemory = FALSE  ) 
 

Clear all fields in this FlmRecord object.

Parameters:
bReleaseMemory  If TRUE, free the memory buffer used to hold field data. If FALSE, the memory buffer will be cleared without freeing it.

RCODE FlmRecord::createFieldIdTable FLMBOOL  bTruncateTable  ) 
 

Create a level one field ID table in a record.

Parameters:
bTruncateTable  Truncate the field id table after sorting?

RCODE FlmRecord::exportRecord HFDB  hDb,
F_Pool *  pPool,
NODE **  ppNode
 

Export a record to a Gedcom NODE tree.

Parameters:
hDb  Database handle. The root node of the Gedcom tree will be associated with this handle.
pPool  Memory pool for allocating NODE structures and space for field data.
ppNode  Root of the Gedcom NODE tree will be returned here.

void* FlmRecord::find void *  pvStartField,
FLMUINT *  puiFieldPath,
FLMUINT  uiOccur = 1,
FLMUINT  uiFindOption = SEARCH_FOREST
 

Find a field in a record that has a particular field path. Search is conducted relative to some other field in the record.

Parameters:
pvStartField  field where search is to start.
puiFieldPath  Field path being searched for.
uiOccur  Occurrence being searched for.
uiFindOption  Specifies how much of the record to search in (relative to pvStartField). It may be one of the following:
  • SEARCH_FOREST - Search the sub-tree beginning at pvStartField, and all subtrees that are next siblings to pvStartField
  • SEARCH_TREE - Search only the sub-tree beginning at pvStartField

void* FlmRecord::find void *  pvStartField,
FLMUINT  uiFieldID,
FLMUINT  uiOccur = 1,
FLMUINT  uiFindOption = SEARCH_FOREST
 

Find a field in a record that has a particular field number. Search is conducted relative to some other field in the record.

Parameters:
pvStartField  Field where search is to start.
uiFieldID  Field number being searched for.
uiOccur  Occurrence being searched for.
uiFindOption  Specifies how much of the record to search in (relative to pvStartField). It may be one of the following:
  • SEARCH_FOREST - Search the sub-tree beginning at pvStartField, and all subtrees that are next siblings to pvStartField
  • SEARCH_TREE - Search only the sub-tree beginning at pvStartField

void* FlmRecord::findLevelOneField FLMUINT  uiFieldID,
FLMBOOL  bFindInclusive,
FLMUINT *  puiFieldPos
 

Find a level one field ID in a record.

Parameters:
uiFieldID  Field number of field to be found.
bFindInclusive  OK to find next field after uiFieldID?
puiFieldPos  Field position in field ID table is returned here.

FINLINE void* FlmRecord::firstChild void *  pvField  )  [inline]
 

Return the first child field of a field. Returns NULL if field has no child fields.

Parameters:
pvField  Field whose first child is to be returned.

RCODE FlmRecord::getBinary void *  pvField,
void *  pvBuf,
FLMUINT *  puiBufLen
 

Get a field's value as binary data.

This method may be used for any type of field, but it really only makes sense for fields whose data type is FLM_BINARY_TYPE. If it is used on a field whose data type is not FLM_BINARY_TYPE, the data returned is in FLAIM's internal storage format.

Parameters:
pvField  Field whose value is to be returned as binary data.
pvBuf  Buffer to hold the binary data.
puiBufLen  On input *puiBufLen is the size of pvBuf (in bytes). On output, it returns the number of bytes in the value. NOTE: If the value length is greater than the *puiBufLen that was passed in, the returned value will be truncated to fit in that buffer. However, no error will be returned.

FINLINE RCODE FlmRecord::getBinaryLength void *  pvField,
FLMUINT *  puiLength
[inline]
 

Get the number of bytes needed to retrieve a field's value as binary data.

This method may be called for any type of field, but it really only makes sense for fields whose data type is FLM_BINARY_TYPE.

Parameters:
pvField  Field whose length is to be returned.
puiLength  Field's length is returned here. NOTE: For fields whose data type is not FLM_BINARY_TYPE, this returns the internal storage length. It really doesn't make much sense to call this method for fields whose data type is not FLM_BINARY_TYPE.

RCODE FlmRecord::getBlob void *  pvField,
FlmBlob **  ppBlob
 

Get a field's value as a FlmBlob object. This method may only be used on field's whose data type is FLM_BLOB_TYPE.

Parameters:
pvField  Field whose value is to be returned as a FlmBlob object.
ppBlob  A pointer to the FlmBlob object is returned here.

FINLINE FLMUINT FlmRecord::getDataLength void *  pvField  )  [inline]
 

Get a field's data length. NOTE: This is the field's internal storage length.

Parameters:
pvField  Field whose data length is to be returned.

FINLINE const FLMBYTE* FlmRecord::getDataPtr void *  pvField  )  [inline]
 

Get a pointer to a field's data.

The returned pointer will be pointing to the data in FLAIM's internal storage format.

Parameters:
pvField  Field whose data pointer is to be returned.

FINLINE FLMUINT FlmRecord::getDataType void *  pvField  )  [inline]
 

Get a field's data type.

Parameters:
pvField  Field whose data type is to be returned.

FLMUINT FlmRecord::getEncFlags void *  pvField  )  [inline]
 

Get a field's encryption flags.

NOTE: This method should NOT be called if the field is not encrypted. Call FlmRecord::isEncryptedField() to determine if the field is encrypted. If called for a non-encrypted field, it will return 0. In debug mode it will also assert.

Parameters:
pvField  Field whose encryption flags are to be returned.

FINLINE FLMUINT FlmRecord::getEncryptedDataLength void *  pvField  )  [inline]
 

Get a field's encrypted data length.

NOTE: This method should NOT be called if the field is not encrypted. Call FlmRecord::isEncryptedField() to determine if the field is encrypted. If called for a non-encrypted field, it will return 0. In debug mode it will also assert.

Parameters:
pvField  Field whose encrypted data length is to be retrieved.

FINLINE const FLMBYTE* FlmRecord::getEncryptionDataPtr void *  pvField  )  [inline]
 

Get a pointer to a field's encrypted data.

NOTE: This method should NOT be called if the field is not encrypted. Call FlmRecord::isEncryptedField() to determine if the field is encrypted. If called for a non-encrypted field, it will return NULL. In debug mode it will also assert.

Parameters:
pvField  Field whose encrypted data pointer is to be retrieved.

FLMUINT FlmRecord::getEncryptionID void *  pvField  )  [inline]
 

Get a field's encryption id.

NOTE: This method should NOT be called if the field is not encrypted. Call FlmRecord::isEncryptedField() to determine if the field is encrypted. If called for a non-encrypted field, it will return 0. In debug mode it will also assert.

Parameters:
pvField  Field whose encryption ID is to be retrieved.

FINLINE FLMUINT FlmRecord::getFieldID void *  pvField  )  [inline]
 

Get the field number for a field.

Parameters:
pvField  Field whose field number is to be returned.

FINLINE RCODE FlmRecord::getFieldInfo void *  pvField,
FLMUINT *  puiFieldNum,
FLMUINT *  puiLevel,
FLMUINT *  puiDataType,
FLMUINT *  puiLength,
FLMUINT *  puiEncLength,
FLMUINT *  puiEncId
[inline]
 

Get information about a field.

Information includes field number, level, data type, data length, encryption length, and encryption id.

Parameters:
pvField  Field whose information is to be retrieved.
puiFieldNum  Field number is returned here.
puiLevel  Field's level is returned here.
puiDataType  Field's data type is returned here.
puiLength  Field's data length is returned here.
puiEncLength  Field's encryption length is returned here. NOTE: This parameter may be NULL.
puiEncId  Field's encryption id is returned here. NOTE: This parameter may be NULL.

RCODE FlmRecord::getINT void *  pvField,
FLMINT *  piNumber
 

Get a field's value as a FLMINT. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.

Parameters:
pvField  Field whose value is to be retrieved (and converted if necessary).
piNumber  Number is returned here.

RCODE FlmRecord::getINT32 void *  pvField,
FLMINT32 *  pi32Number
 

Get a field's value as a FLMINT32. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.

Parameters:
pvField  Field whose value is to be retrieved (and converted if necessary).
pi32Number  Number is returned here.

RCODE FlmRecord::getINT64 void *  pvField,
FLMINT64 *  pi64Number
 

Get a field's value as a FLMINT64. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.

Parameters:
pvField  Field whose value is to be retrieved (and converted if necessary).
pi64Number  Number is returned here.

FINLINE FLMUINT FlmRecord::getLevel void *  pvField  )  [inline]
 

Get the nesting level of a field in the record.

The nesting level begins at 0 (root field), 1 (children of the root field), 2 (grandchildren of the root field), etc.

Parameters:
pvField  Field whose nesting level is to be returned.

void* FlmRecord::getLevelOneField FLMUINT  uiFieldId,
FLMUINT  uiLevelOnePosition
 

Determine if the level one field at the specified position in the field ID table matches the passed in field ID. If so, return that field pointer.

Parameters:
uiFieldId  Field id to be matched.
uiLevelOnePosition  Level one field position to be checked.

FLMUINT FlmRecord::getLevelOneFieldId FLMUINT  uiLevelOnePosition  ) 
 

Get the field ID of the field that is in the specified position in the field ID table.

Parameters:
uiLevelOnePosition  Level one field position whose field ID is to be returned.

RCODE FlmRecord::getNative void *  pvField,
char *  pszStrBuf,
FLMUINT *  puiStrBufLen
 

Get a field's value as a native string. Note that the field may be a FLM_NUMBER_TYPE, or FLM_TEXT_TYPE.

Parameters:
pvField  Field whose data is to be returned as a native string.
pszStrBuf  Buffer to hold the native string. NOTE: If this parameter is NULL then *puiStrBufLen will return the number of bytes needed to hold the string. However, that does NOT count the byte needed to null-terminate the string. Thus, if the application is calling this routine to find out how big of a buffer to allocate to hold the string, it should add 1 to the value returned in *puiStrBufLen.
puiStrBufLen  On input *puiStrBufLen should be the number of bytes available in pszStrBuf. pszStrBuf should be large enough to hold a null terminating character. On output *puiStrBufLen returns the number of bytes needed to hold the converted native string. NOTE: The null termination byte is NOT included in this value.

FINLINE RCODE FlmRecord::getNativeLength void *  pvField,
FLMUINT *  puiLength
[inline]
 

Get the number of bytes needed to retrieve a field's value as a native string.

The value may be either a FLM_NUMBER_TYPE or a FLM_TEXT_TYPE. The length returned does NOT account for null-termination, so if the application is calling this routine to determine how big of a buffer to allocate, it should add 1 to the size returned from this routine.

Parameters:
pvField  Field containing the value whose native string length is to be determined.
puiLength  Native length is returned (in bytes). The length does not include what it would take for null-termination.

RCODE FlmRecord::getRecPointer void *  pvField,
FLMUINT *  puiRecPointer
 

Get the value for a FLM_CONTEXT_TYPE field as a FLMUINT.

Parameters:
pvField  Field whose value is to be returned.
puiRecPointer  Value is returned here.

FINLINE RCODE FlmRecord::getRecPointer32 void *  pvField,
FLMUINT32 *  pui32RecPointer
[inline]
 

Get the value for a FLM_CONTEXT_TYPE field as a FLMUINT32.

Parameters:
pvField  Field whose value is to be returned.
pui32RecPointer  Value is returned here.

RCODE FlmRecord::getUINT void *  pvField,
FLMUINT *  puiNumber
 

Get a field's value as a FLMUINT. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.

Parameters:
pvField  Field whose value is to be retrieved (and converted if necessary).
puiNumber  Number is returned here.

RCODE FlmRecord::getUINT32 void *  pvField,
FLMUINT32 *  pui32Number
 

Get a field's value as a FLMUINT32. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.

Parameters:
pvField  Field whose value is to be retrieved (and converted if necessary).
pui32Number  Number is returned here.

RCODE FlmRecord::getUINT64 void *  pvField,
FLMUINT64 *  pui64Number
 

Get a field's value as a FLMUINT64. Data conversions will be done if the field is a FLM_CONTEXT_TYPE or FLM_TEXT_TYPE.

Parameters:
pvField  Field whose value is to be retrieved (and converted if necessary).
pui64Number  Number is returned here.

RCODE FlmRecord::getUnicode void *  pvField,
FLMUNICODE *  puzStrBuf,
FLMUINT *  puiStrBufLen
 

Get a field's value as a unicode string. Note that the field may be a FLM_NUMBER_TYPE, or FLM_TEXT_TYPE.

Parameters:
pvField  Field whose data is to be returned as a unicode string.
puzStrBuf  Buffer to hold the Unicode string. NOTE: If this parameter is NULL then *puiStrBufLen will return the number of bytes needed to hold the string. However, that does NOT count the two bytes needed to null-terminate the string. Thus, if the application is calling this routine to find out how big of a buffer to allocate to hold the string, it should add 2 to the value returned in *puiStrBufLen.
puiStrBufLen  On input *puiStrBufLen should be the number of bytes available in puzStrBuf. puzStrBuf should be large enough to hold a unicode null terminating character (2 bytes). On output *puiStrBufLen returns the number of bytes needed to hold the converted Unicode string. NOTE: The two null termination bytes are NOT included in this value.

FINLINE RCODE FlmRecord::getUnicodeLength void *  pvField,
FLMUINT *  puiLength
[inline]
 

Get the number of bytes needed to retrieve a field's value as a unicode string.

The value may be either a FLM_NUMBER_TYPE or a FLM_TEXT_TYPE. The length returned does NOT account for null-termination, so if the application is calling this routine to determine how big of a buffer to allocate, it should add 2 to the size returned from this routine.

Parameters:
pvField  Field containing the value whose unicode string length is to be determined.
puiLength  Unicode length is returned (in bytes). The length does not include what it would take for null-termination.

FINLINE FLMBOOL FlmRecord::hasChild void *  pvField  )  [inline]
 

Determine if a field has any child fields.

Parameters:
pvField  Field that is to be checked for child fields.

RCODE FlmRecord::importRecord NODE pNode  ) 
 

Import a record from a Gedcom NODE tree.

Parameters:
pNode  Node that is the root of a Gedcom tree to be imported.

RCODE FlmRecord::importRecord const char **  ppszBuffer,
FLMUINT  uiBufSize,
F_NameTable pNameTable
 

Import a record from a string buffer.

The record in the string should be formatted according to the specification for GEDCOM.

Parameters:
ppszBuffer  Buffer containing the data that is to be imported.
uiBufSize  Number of bytes in the buffer.
pNameTable  Name table object that is to be used to translate field names to field numbers.

RCODE FlmRecord::importRecord IF_FileHdl *  pFileHdl,
F_NameTable pNameTable
 

Import a record from a file.

The record in the file should be formatted according to the specification for GEDCOM.

Parameters:
pFileHdl  Open file handle where the data for the record is to be read from.
pNameTable  Name table object that is to be used to translate field names to field numbers.

RCODE FlmRecord::insert void *  pvField,
FLMUINT  uiInsertAt,
FLMUINT  uiFieldID,
FLMUINT  uiDataType,
void **  ppvField
 

Insert a new field into the FlmRecord object. Insertion is relative to an already existing field.

Parameters:
pvField  Field that already exists in the record. New field is created relative to this field.
uiInsertAt  Relative position with respect to pvField where new field is to be created. It may be one of the following:
  • INSERT_PREV_SIB - insert new field as the previous sibling of pvField
  • INSERT_NEXT_SIB - insert new field as the next sibling of pvField
  • INSERT_FIRST_CHILD - insert new field as the first child of pvField
  • INSERT_LAST_CHILD - insert new field as the last child of pvField
uiFieldID  Field number for new field. This should be a valid field number as defined in the data dictionary.
uiDataType  Data type for new field. This may be one of the following:
  • FLM_TEXT_TYPE
  • FLM_NUMBER_TYPE
  • FLM_BINARY_TYPE
  • FLM_CONTEXT_TYPE
  • FLM_BLOB_TYPE
ppvField  Pointer to newly created field is returned here.

RCODE FlmRecord::insertLast FLMUINT  uiLevel,
FLMUINT  uiFieldID,
FLMUINT  uiDataType,
void **  ppvField
 

Insert a new field into the FlmRecord object.

New field is always inserted as the last field in the record.

Parameters:
uiLevel  Nesting level for the new field. NOTE: If this is the first field created in the record, the nesting level must be zero. Only the first field added may have a nesting level of zero. If this is not the first field in the record, the nesting level must be between 1 and N+1, where N is the level of the current last field in the record.
uiFieldID  Field number for new field. This should be a valid field number as defined in the data dictionary.
uiDataType  Data type for new field. This may be one of the following:
  • FLM_TEXT_TYPE
  • FLM_NUMBER_TYPE
  • FLM_BINARY_TYPE
  • FLM_CONTEXT_TYPE
  • FLM_BLOB_TYPE
ppvField  Pointer to newly created field is returned here.

FINLINE FLMBOOL FlmRecord::isEncryptedField void *  pvField  )  [inline]
 

Determine if a field is encrypted.

Parameters:
pvField  Field that is to be checked to see if it is encrypted.

FINLINE FLMBOOL FlmRecord::isLast void *  pvField  )  [inline]
 

Determine if a field has a next sibling field.

Parameters:
pvField  Field that is to be checked for next sibling fields.

FINLINE FLMBOOL FlmRecord::isLeftTruncated void *  pvField  )  [inline]
 

Determine if field is marked as "left truncated." This really only applies to binary data or strings.

It indicates that data at the beginning of the binary value or string value is missing.

Parameters:
pvField  Field that is to be checked to see if it is "left truncated."

FINLINE FLMBOOL FlmRecord::isRightTruncated void *  pvField  )  [inline]
 

Determine if field is marked as "right truncated." This really only applies to binary data or strings.

It indicates that data at the end of the binary value or string value is missing.

Parameters:
pvField  Field that is to be checked to see if it is "right truncated."

FINLINE void* FlmRecord::lastChild void *  pvField  )  [inline]
 

Return the last child field of a field. Returns NULL if field has no child fields.

Parameters:
pvField  Field whose last child is to be returned.

FINLINE void* FlmRecord::next void *  pvField  )  [inline]
 

Return the "next" field of a field.

If the field has child fields, then "next" means first child. If the field has no child fields, but has siblings, then "next" means next sibling. If the field has no next sibling field, then "next" means the next sibling of the field's parent field (if any), or the next sibling of the grandparent field (if any), etc. If there is no next sibling to a parent, grandparent, etc., then NULL will be returned.

Parameters:
pvField  Field whose "next" field is to be returned.

void* FlmRecord::nextLevelOneField FLMUINT *  puiFieldPos,
FLMBOOL  bFieldIdsMustMatch
 

Get the next level one field after the position specified. Make sure that the next field has the same field ID as the current field.

Parameters:
puiFieldPos  Current level one field position. Returns the next level one field position.
bFieldIdsMustMatch  Specifies whether the field ID of the next field in the field ID table must match the field ID of the current field position.

FINLINE void* FlmRecord::nextSibling void *  pvField  )  [inline]
 

Return the next sibling field of a field. Returns NULL if there is no next sibling field.

Parameters:
pvField  Field whose next sibling is to be returned.

void FlmRecord::operator delete[] void *  ptr  ) 
 

Overloaded delete operator (array) for FlmRecord objects. Pointer to array of FlmRecord objects being freed.

This method is called when an array of FlmRecord objects is freed.

void* FlmRecord::operator new FLMSIZET  uiSize,
const char *  pszFile,
int  iLine
throw ()
 

Overloaded new operator for ::FlmRecord objects (with source file and line number).

This new operator passes in the current file and line number. This information is useful in tracking memory allocations to determine where memory leaks are coming from.

Parameters:
uiSize  Number of bytes to allocate - should be sizeof( ::FlmRecord).
pszFile  Name of source file where this allocation is made.
iLine  Line number in source file where this allocation request is made.

void* FlmRecord::operator new FLMSIZET  uiSize  )  throw ()
 

Overloaded new operator for FlmRecord objects.

Parameters:
uiSize  Number of bytes to allocate - should be sizeof( ::FlmRecord).

void* FlmRecord::operator new[] FLMSIZET  uiSize,
const char *  pszFile,
int  iLine
throw ()
 

Overloaded new operator (array) for FlmRecord objects (with source file and line number).

This new operator is called when an array of FlmRecord objects is allocated. This new operator passes in the current file and line number. This information is useful in tracking memory allocations to determine where memory leaks are coming from.

Parameters:
uiSize  Number of bytes to allocate - should be a multiple of sizeof( ::FlmRecord).
pszFile  Name of source file where this allocation is made.
iLine  Line number in source file where this allocation request is made.

void* FlmRecord::operator new[] FLMSIZET  uiSize  )  throw ()
 

Overloaded new operator (array) for FlmRecord objects.

This method is called when an array of FlmRecord objects is allocated.

Parameters:
uiSize  Number of bytes to allocate - should be a multiple of sizeof( ::FlmRecord).

FINLINE void* FlmRecord::parent void *  pvField  )  [inline]
 

Return the parent field of a field. Returns NULL if the field is the "root" field of the record.

Parameters:
pvField  Field whose parent is to be returned.

FINLINE void* FlmRecord::prev void *  pvField  )  [inline]
 

Return the "previous" field of a field.

If the field has a previous sibling field, and that previous sibling has children, grandchildren, etc., then "previous" means previous sibling's last child's, last child, last child (etc.). If the previous sibling field has no children, then "previous" means previous sibling. If there is no previous sibling, then "previous" means parent field. If the field is the "root" field, then NULL will be returned.

Parameters:
pvField  Field whose "previous" field is to be returned.

void* FlmRecord::prevSibling void *  pvField  ) 
 

Return the previous sibling field of a field. Returns NULL if there is no previous sibling field.

Parameters:
pvField  Field whose previous sibling is to be returned.

FINLINE FLMINT FLMAPI FlmRecord::Release void   )  [inline]
 

Decrement the reference count for this FlmRecord object.

The reference count is the number of pointers that are referencing this FlmRecord object. Return value is the decremented reference count. If the reference count goes to zero, the FlmRecord object will be deleted.

FINLINE RCODE FlmRecord::remove void *  pvField  )  [inline]
 

Remove a field from a record. The field and all of its descendant fields will be removed from the record.

Parameters:
pvField  Field to be removed. NOTE: If the field has descendant fields, all of those fields will also be removed.

RCODE FlmRecord::setBinary void *  pvField,
const void *  pvBuf,
FLMUINT  uiBufLen,
FLMUINT  uiEncId = 0
 

Set a field's value to a binary value. The resulting data type for the field will be FLM_BINARY_TYPE.

Parameters:
pvField  Field whose value is to be set.
pvBuf  Binary value to set.
uiBufLen  Length of binary data (in bytes).
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.

RCODE FlmRecord::setBlob void *  pvField,
FlmBlob pBlob,
FLMUINT  uiEncId = 0
 

Set a field's value to a BLOB value. The resulting data type for the field will be FLM_BLOB_TYPE.

Parameters:
pvField  Field whose value is to be set.
pBlob  BLOB value to set.
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.

FINLINE void FlmRecord::setFieldID void *  pvField,
FLMUINT  uiFieldID
[inline]
 

Set the field number for a field.

Parameters:
pvField  Field whose field number is to be set.
uiFieldID  Field number to be set.

RCODE FlmRecord::setINT void *  pvField,
FLMINT  iNumber,
FLMUINT  uiEncId = 0
 

Set a field's value to a FLMINT value. The resulting data type for the field will be FLM_NUMBER_TYPE.

Parameters:
pvField  Field whose value is to be set.
iNumber  Value to set.
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.

RCODE FlmRecord::setINT64 void *  pvField,
FLMINT64  i64Number,
FLMUINT  uiEncId = 0
 

Set a field's value to a FLMINT64 value. The resulting data type for the field will be FLM_NUMBER_TYPE.

Parameters:
pvField  Field whose value is to be set.
i64Number  Value to set.
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.

FINLINE void FlmRecord::setLeftTruncated void *  pvField,
FLMBOOL  bTrueFalse
[inline]
 

Set a flag for a field indicating if its value has been "left truncated." Left truncation really only applies to binary data or strings.

It specifies that data at the beginning of the binary value or string value is missing.

Parameters:
pvField  Field that is to be marked as "left truncated" or "not left truncated."
bTrueFalse  Flag indicating if field is to be marked as "left truncated" or "not left truncated."

RCODE FlmRecord::setNative void *  pvField,
const char *  pszString,
FLMUINT  uiEncId = 0
 

Set a field's value to a native string value. The resulting data type for the field will be FLM_TEXT_TYPE.

Parameters:
pvField  Field whose value is to be set.
pszString  Value to set. This should be a null-terminated native string.
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.

RCODE FlmRecord::setRecPointer void *  pvField,
FLMUINT  uiRecPointer,
FLMUINT  uiEncId = 0
 

Set a field's value to a FLMUINT value. The resulting data type for the field will be FLM_CONTEXT_TYPE.

Parameters:
pvField  Field whose value is to be set.
uiRecPointer  Value to set.
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.

FINLINE void FlmRecord::setRightTruncated void *  pvField,
FLMBOOL  bTrueFalse
[inline]
 

Set a flag for a field indicating if its value has been "right truncated." Right truncation really only applies to binary data or strings.

It specifies that data at the end of the binary value or string value is missing.

Parameters:
pvField  Field that is to be marked as "right truncated" or "not right truncated."
bTrueFalse  Flag indicating if field is to be marked as "right truncated" or "not right truncated."

RCODE FlmRecord::setUINT void *  pvField,
FLMUINT  uiNumber,
FLMUINT  uiEncId = 0
 

Set a field's value to a FLMUINT value. The resulting data type for the field will be FLM_NUMBER_TYPE.

Parameters:
pvField  Field whose value is to be set.
uiNumber  Value to set.
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.

RCODE FlmRecord::setUINT64 void *  pvField,
FLMUINT64  ui64Number,
FLMUINT  uiEncId = 0
 

Set a field's value to a FLMUINT64 value. The resulting data type for the field will be FLM_NUMBER_TYPE.

Parameters:
pvField  Field whose value is to be set.
ui64Number  Value to set.
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.

RCODE FlmRecord::setUnicode void *  pvField,
const FLMUNICODE *  puzUnicode,
FLMUINT  uiEncId = 0
 

Set a field's value to a Unicode string value. The resulting data type for the field will be FLM_TEXT_TYPE.

Parameters:
pvField  Field whose value is to be set.
puzUnicode  Value to set. This should be a null-terminated Unicode string.
uiEncId  Encryption ID. If zero, the value will not be encrypted. If non-zero, the number should be the ID of an encryption definition record in the data dictionary. The encryption key for that encryption definition will be used to encrypt this value.


Generated on Wed Oct 4 12:11:43 2006 for FLAIM by  doxygen 1.4.6