IAAFTextLocator Interface Reference

The IAAFTextLocator interface is implemented by objects which provide information to help find a file containing essence data in a descriptive way for files that are held off-line. More...

List of all members.

Public Member Functions
HRESULT	Initialize ()
	Initializes a newly allocated, empty IAAFNetworkLocator-supporting object.
HRESULT	SetName ([in, string] aafCharacter_constptr pName)
	Sets the Name string property.
HRESULT	GetName ([out, string, size_is(bufSize)] aafCharacter *pName,[in] aafUInt32 bufSize)
	Gets the Name string property.
HRESULT	GetNameBufLen ([out] aafUInt32 *pBufSize)
	Returns size of buffer (in bytes) required for GetName().

---

Detailed Description

The IAAFTextLocator interface is implemented by objects which provide information to help find a file containing essence data in a descriptive way for files that are held off-line.

In addition to the specific error results listed for each method, all methods in this interface may also return one of the following values:

AAFRESULT_NOMEMORY

• insufficient system memory is available to perform the operation.

AAFRESULT_NOT_INITIALIZED

• This object has not yet had Initialize() called on it through this object's primary interface.

Objects that implement IAAFTextLocator also implement the following interfaces:

• IAAFLocator
• IAAFObject

Definition at line 27715 of file AAF.idl.

---

Member Function Documentation

HRESULT IAAFTextLocator::GetName	(	[out, string, size_is(bufSize)] aafCharacter *	pName,
		[in] aafUInt32	bufSize
	)

Gets the Name string property.

Writes the Name property, with a trailing null character, into the pName buffer. The buffer is allocated by the caller. The size of the buffer is given by bufSize. If the Name property has not yet been set, a zero-length string will be written (that is, only the trailing null character).

Caller may call GetNameBufLen() to determine the required buffer size.

If this method fails nothing will be written to pName.

Succeeds if:

• The pName pointer is valid.
• bufSize indicates that the buffer is large enough to hold Name.

This method will return the following codes. If more than one of the listed errors is in effect, it will return the first one encountered in the order given below:

AAFRESULT_SUCCESS

• succeeded. (This is the only code indicating success.)

AAFRESULT_NULL_PARAM

• pName arg is NULL.

AAFRESULT_SMALL_BUF

• bufSize indicates that the allocated buffer is not large enough to hold Name.

Parameters:

pName	[out, string, size_is(bufSize)] buffer into which Name is to be written
bufSize	[in] size of *pName buffer in bytes

HRESULT IAAFTextLocator::GetNameBufLen

(

[out] aafUInt32 *

pBufSize

)

Returns size of buffer (in bytes) required for GetName().

Succeeds if:

• The pBufSize pointer is valid.

This method will return the following codes. If more than one of the listed errors is in effect, it will return the first one encountered in the order given below:

AAFRESULT_SUCCESS

• succeeded. (This is the only code indicating success.)

AAFRESULT_NULL_PARAM

• pBufSize arg is NULL.

Parameters:

pBufSize

[out] size of required buffer, in bytes

HRESULT IAAFTextLocator::Initialize

(

)

Initializes a newly allocated, empty IAAFNetworkLocator-supporting object.

This method must be called after allocation, and before any other method can be called.

Succeeds if:

• Initialize() has not yet been called on this object.

This method will return the following codes. If more than one of the listed errors is in effect, it will return the first one encountered in the order given below:

AAFRESULT_SUCCESS

• succeeded. (This is the only code indicating success.)

AAFRESULT_ALREADY_INITIALIZED

• Initialize() has already been called on this object.

HRESULT IAAFTextLocator::SetName

(

[in, string] aafCharacter_constptr

pName

)

Sets the Name string property.

Set the Name property to the value specified in pName. A copy is made of the data so the caller retains ownership of the *pName buffer and is responsible for de-allocating it. There is no pre-set limit to the length of the name, other than available system memory or disk space.

Succeeds if all of the following are true:

• the pName pointer is valid.

If this method fails the Name property will not be changed.

This method will return the following codes. If more than one of the listed errors is in effect, it will return the first one encountered in the order given below:

AAFRESULT_SUCCESS

• succeeded. (This is the only code indicating success.)

AAFRESULT_NULL_PARAM

• pName arg is NULL.

Parameters:

pName

[in, string] buffer from which Name is to be read