Retired Document
Important: Apple recommends that developers explore QTKit and Core Video for new development in this technology area. See QTKit Framework Reference and Core Video Programming Guide for more information.
This section describes the QTSS callback routines that modules call to obtain information from the server, allocate and deallocate memory, create objects, get and set attribute values, and manage client and RTSP sessions.
QTSS Utility Callback Routines
Modules call the following callback routines to register for roles, allocate and deallocate memory, get the value of the server’s internal timer, and to convert a value from the internal timer to the current time.
QTSS_AddRole
Adds a role.
QTSS_Error QTSS_AddRole(QTSS_Role inRole);
Parameters
- inRole
On input, a value of type
QTSS_Role
that specifies the role that is to be added.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_OutOfState
ifQTSS_AddRole
is called from a role other than the Register role,QTSS_RequestFailed
if the module is registering for the RTSP Request role and a module is already registered for that role, andQTSS_BadArgument
if the specified role does not exist.
Discussion
The
QTSS_AddRole
callback routine tells the server that your module can be called for the role specified byinRole
.The
QTSS_AddRole
callback can only be called from a module’s Register role. For this version of the server, you can add the following roles:QTSS_ClientSessionClosing_Role
,QTSS_ErrorLog_Role
, QTSS_Initialize_Role,QTSS_OpenFilePreprocess_Role, QTSS_OpenFile_Role, QTSS_RTSPFilter_Role
,QTSS_RTSPRoute_Role, QTSS_RTSPPreProcessor_Role, QTSS_RTSPRequest_Role, QTSS_RTSPPostProcessor_Role, QTSS_RTPSendPackets_Role, QTSS_RTCPProcess_Role,
QTSS_Shutdown_Role
.
QTSS_New
Allocates memory.
void* QTSS_New( FourCharCode inMemoryIdentifier, UInt32 inSize);
Parameters
- inMemoryIdentifier
On input, a value of type
FourCharCode
that will be associated with this memory allocation. The server can track the allocated memory to make debugging memory leaks easier.- inSize
On input, a value of type
UInt32
that specifies in bytes the amount of memory to be allocated.- result
None.
Discussion
The
QTSS_New
callback routine allocates memory. QTSS modules should callQTSS_New
whenever it needs to allocate memory dynamically.To delete the memory that
QTSS_New
allocates, callQTSS_Delete
.QTSS_Delete
Deletes memory.
void* QTSS_Delete(void* inMemory);
Parameters
- inMemory
On input, a pointer to an arbitrary value that specifies in bytes the amount of memory to be deleted.
- result
None.
Discussion
The
QTSS_Delete
callback routine deletes memory that was previously allocated byQTSS_New
.QTSS_Milliseconds
Gets the current value of the server’s internal clock.
QTSS_TimeVal QTSS_Milliseconds();
Parameters
- result
The value of the server’s internal clock in milliseconds since midnight January 1, 1970.
Discussion
The
QTSS_Milliseconds
callback routine gets the current value of the server’s internal clock since midnight January 1, 1970. Unless otherwise noted, all millisecond values that the server provides in attributes are obtained from this clock.QTSS_MilliSecsTo1970Secs
Converts a value obtained from the server’s internal clock to the current time.
time_t QTSS_MilliSecsTo1970Secs(QTSS_TimeVal inQTSS_Milliseconds);
Parameters
- inQTSS_Milliseconds
On input, a value of type
QTSS_TimeVal
obtained by callingQTSS_Milliseconds()
.- result
A value of type
time_t
containing the current time.
Discussion
The
QTSS_MilliSecsto1970Secs
callback routine converts a value obtained by callingQTSS_Milliseconds
to the current time.
QTSS Object Callback Routines
Modules call the object callback routines to create, lock, and unlock o bjects.
QTSS_CreateObjectType
Creates an object type.
QTSS_Error QTSS_CreateObjectType(QTSS_ObjectType* outType);
Parameters
- outType
On input, a pointer to a value of type
QTSS_ObjectType
.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_FailedRequest
too many object types already exist, andQTSS_OutOfState
ifQTSS_CreateObjectType
an attribute of the specified name already exists.
Discussion
The
QTSS_CreateObjectType
callback routine creates a new object type and provides a pointer to it. Static attributes can be added to the object type by callingQTSS_AddStaticAttribute
. Instance attributes can be added to instances of objects of the new object type.The
QTSS_AddStaticAttribute
callback can only be called from the Register role. CallQTSS_SetValue
to set the value of an added attribute andQTSS_RemoveValue
to remove the value of an added attribute.This callback may only be called from the Register role.
QTSS_CreateObjectValue
Creates a new object that is the value of another object’s attribute.
QTSS_Error QTSS_CreateObjectValue( QTSS_Object inObject, QTSS_AttributeID inID, QTSS_ObjectType inType, UInt32* outIndex, QTSS_Object* outCreatedObject);
Parameters
- inObject
On input, a pointer to a value of type
QTSS_ObjectType
that specifies the object having an attribute whose value will be the created object.- inID
On input, a value of type
QTSS_AttributeID
that specifies the attribute ID of the attribute whose value will be the created object.- inType
On input, a value of type
QTSS_ObjectType
that specifies the object type of the object that is to be created.- outIndex
On output, a pointer to a value of type
UInt32
that contains the index of the created object.- outCreatedObject
On output, a pointer to a value of type
QTSS_ObjectType
s that is the new object.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_BadArgument
ifany parameter is invalid, and
QTSS_ReadOnly
if the attribute specified byinID
is a read-only attribute.
Discussion
The
QTSS_CreateObjectValue
callback routine creates an object that is the value of an existing object’s attribute. The object specified by inObject is the “parent” object.If the object specified by inObject is later locked by calling
QTSS_LockObject
, the object pointed to by outCreatedObject is also locked.QTSS_LockObject
Locks an object.
QTSS_Error QTSS_LockObject(QTSS_Object inObject);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object that is to be locked.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if the specified object instance does not exist.
Discussion
The
QTSS_LockObject
callback routine locks the specified object so that accesses to the object’s attributes from other threads will block. CallQTSS_LockObject
before performing non-atomic updates on a variable that is pointed to by an attribute—as set by callingQTSS_SetValuePtr
—or before getting the value of a non-preemptive safe attribute.Call
QTSS_UnLockObject
to unlock the object.Objects created by
QTSS_CreateObjectValue
are locked when the parent object is locked.QTSS_UnLockObject
Unlocks an object.
QTSS_Error QTSS_UnLockObject(QTSS_Object inObject);
Parameters
- inObject
On input, a value of type
QTSS_Object
that is to be unlocked.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if the specified object is not a valid object.
Discussion
The
QTSS_UnLockObject
callback routine unlocks an object that was previously locked byQTSS_LockObject
.
QTSS Attribute Callback Routines
Modules call the attribute callback routines to work with attributes.
QTSS_AddInstanceAttribute
Adds an instance attribute to the instance of an object.
QTSS_Error QTSS_AddInstanceAttribute( QTSS_Object inObject, char* inAttrName, void* inUnused, QTSS_AttrDataType inAttrDataType);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object to which the instance attribute is to be added.- inAttrName
On input, a pointer to a byte array that specifies the name of the attribute that is to be added.
- inUnused
Always
NULL
.- QTSS_AttrDataType
On input, a value of type
QTSS_AttrDataType
that specifies the data type of the attribute that is being added.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_OutOfState
ifQTSS_AddInstanceAttribute
is called from a role other than the Register role,QTSS_BadArgument
if the specified object type does not exist, the attribute name is too long, or a parameter is not specified, andQTSS_AttrNameExists
if an attribute of the specified name already exists.
Discussion
The
QTSS_AddInstanceAttribute
callback routine adds an attribute to the instance of an object as specified by theinObject
parameter. This callback can only be called from the Register role.When adding attributes to an object that a module as created, you must lock the object first by calling
QTSS_LockObject
. Add the attributes and then callQTSS_UnLockObject
.All added instance attributes have values that are implicitly readable, writable, and preemptive safe, so their values can be obtained by calling
QTSS_GetValueAsString
andQTSS_GetValuePtr
. You can also callQTSS_GetValue
to get the value of an added static attribute, but doing so is less efficient.Adding static attributes is more efficient than adding instance attributes, so adding static attributes instead of adding instance attributes is strongly recommended.
Typically, a module adds an instance attribute and sets its value by calling
QTSS_SetValue
when it is first installed to add its default preferences to its module preferences object. On subsequent runs of the server, the preferences will already exist in the module’s module preferences object, so the module only needs to callQTSS_GetValue
,QTSS_GetValueAsString
, orQTSS_GetValuePtr
to get the value. CallingQTSS_GetValuePtr
is the most efficient and recommended way to get the value of an attribute. CallingQTSS_GetValue
is less efficient than callingQTSS_GetValuePtr
, and callingQTSS_GetValueAsString
is less efficient than callingQTSS_GetValue
.Call
QTSS_RemoveValue
to remove the value of an added attribute.Unlike static attributes, instance attributes can be removed. To remove an instance attribute from the instance of an object, call
QTSS_RemoveInstanceAttribute
.QTSS_AddStaticAttribute
Adds a static attribute to an object type.
QTSS_Error QTSS_AddStaticAttribute( QTSS_ObjectType inObjectType, const char* inAttributeName, void* inUnused, QTSS_AttrDataType inAttrDataType);
Parameters
- inType
On input, a value of type
QTSS_ObjectType
that specifies the type of object to which the attribute is to be added.- inAttributeName
On input, a pointer to a byte array that specifies the name of the attribute that is to be added.
- inUnused
Always
NULL
.- QTSS_AttrDataType
On input, a value of type
QTSS_AttrDataType
that specifies the data type of the attribute that is being added.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_OutOfState
ifQTSS_AddStaticAttribute
is called from a role other than the Register role,QTSS_BadArgument
if the specified object type does not exist, the attribute name is too long, or a parameter is not specified, andQTSS_AttrNameExists
if an attribute of the specified name already exists.
Discussion
The
QTSS_AddStaticAttribute
callback routine adds the specified attribute to all objects of the type specified by theinType
parameter. This callback can only be called from the Register role. Once added, static attributes cannot be removed while the server is running.When adding attributes to an object that a module as created, you must lock the object first by calling
QTSS_LockObject
. Add the attributes and then callQTSS_UnLockObject
.Adding static attributes is more efficient than adding instance attributes, so adding static attributes instead of instance attributes is strongly recommended.
The values of all added static attributes are implicitly readable, writable, and preemptive safe. Call
QTSS_SetValue
orQTSS_SetValuePtr
to set the value of an added attribute.Call
QTSS_GetValuePtr
,QTSS_GetValue
orQTSS_GetValueAsString
to get the value of a static attribute that has been added. CallingQTSS_GetValuePtr
is the most efficient and recommended way to get the value of an attribute. CallingQTSS_GetValue
is less efficient than callingQTSS_GetValuePtr
, and callingQTSS_GetValueAsString
is less efficient than callingQTS_GetValue
.Call
QTSS_RemoveValue
to remove the value of an added static attribute.QTSS_GetAttrInfoByID
Uses an attribute ID to get information about an attribute.
QTSS_Error QTSS_GetAttrInfoByID( QTSS_Object inObject, QTSS_AttributeID inAttrID, QTSS_AttrInfoObject* outAttrInfoObject);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object having the attribute for which information is to be obtained.- inAttrID
On input, a value of type
QTSS_AttributeID
that specifies the attribute for which information is to be obtained.- outAttrInfoObject
On output, a pointer to a value of type
QTSS_AttrInfoObject
that can be used to get information about the attribute specified byinAttrID
.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_BadArgument
if the specified object does not exist, andQTSS_AttrDoesntExist
if the attribute doesn’t exist.
Discussion
The
QTSS_GetAttrInfoByID
callback routine uses an attribute ID to get anQTSS_AttrInfoObject
that can be used to get the attribute’s name, data type, permissions for reading and writing the attribute’s value, and whether getting the attribute’s value is preemptive safe.QTSS_GetAttrInfoByIndex
Gets information about all of an object’s attributes by iteration.
QTSS_Error QTSS_GetAttrInfoByIndex( QTSS_Object inObject, UInt32 inIndex, QTSS_AttrInfoObject* outAttrInfoObject);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object having the attribute for which information is to be obtained.- inIndex
On input, a value of type
UInt32
that specifies the index of the attribute for which information is to be obtained. Start by settinginIndex
to zero. For the next call toQTSS_GetAttrInfoByIndex
, incrementinIndex
by one to get information for the next attribute. CallQTSS_GetNumAttributes
to get the number of attributes thatinObject
has.- outAttrInfoObject
On output, a pointer to a value of type
QTSS_AttrInfoObject
that can be used to get information about the attribute specified byinAttrName
.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_BadArgument
if the specified object does not exist, andQTSS_AttrDoesntExist
if the attribute doesn’t exist.
Discussion
The
QTSS_GetAttrInfoByIndex
callback routine uses an index to get anQTSS_AttrInfoObject
that can be used to get the attribute’s name and ID, data type, permissions for reading and write the attribute’s value, and whether getting the attribute’s value is preemptive safeThe
QTSS_GetAttrInfoByIndex
callback routine returns aQTSS_AttrInfoObject
for both static and instance attributes.QTSS_GetAttrInfoByName
Uses an attribute’s name to get information about an attribute.
QTSS_Error QTSS_GetAttrInfoByName( QTSS_Object inObject, char* inAttrName, QTSS_AttrInfoObject* outAttrInfoObject);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object having the attribute for which information is to be obtained.- inAttrName
On input, a pointer to a C string containing the name of the attribute for which information is to be obtained.
- outAttrInfoObject
On output, a pointer to a value of type
QTSS_AttrInfoObject
that can be used to get information about the attribute specified byinAttrName
.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_BadArgument
if the specified object does not exist, andQTSS_AttrDoesntExist
if the attribute doesn’t exist.
Discussion
The
QTSS_GetAttrInfoByName
callback routine uses an attribute name to get anQTSS_AttrInfoObject
that can be used to get the attribute’s ID, its data type, and permissions for reading and writing the attribute’s value, and whether getting the attribute’s value is preemptive safe.The
QTSS_GetAttrInfoByName
callback routine returns aQTSS_AttrInfoObject
for both static and instance attributes.QTSS_GetNumAttributes
Gets a count of an object’s attributes.
QTSS_Error QTSS_GetNumAttributes( QTSS_Object inObject, UInt32* outNumAttributes);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object whose attributes are to be counted.- outNumAttributes
On output, a pointer to a value of type
UInt32
that contains the count of the object’s attributes.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if the specified object does not exist.
Discussion
The
QTSS_GetNumAttributes
callback routine gets the number of attributes for the object specified byinObject
. Having the number of attributes lets you know how often to callQTSS_GetAttrInfoByIndex
when getting information about each of an object’s attributes.QTSS_GetValue
Copies the value of an attribute into a buffer.
QTSS_Error QTSS_GetValue ( QTSS_Object inObject, QTSS_AttributeID inID, UInt32 inIndex, void* ioBuffer, UInt32* ioLen);
Parameters
- inObject
On input, a value of type
QTSS_Object
specifying the object that contains the attribute whose value is to be obtained.- inID
On input, a value of type
QTSS_AttributeID
specifying the ID of the attribute whose value is to be obtained.- inIndex
On input, a value of type
UInt32
that specifies which attribute value to get (if the attribute can have multiple values) or zero for single-value attributes.- ioBuffer
On input, a pointer to a buffer. On output, the buffer pointed to by
ioBuffer
contains the value of the attribute specified byinID
. If the buffer is too small to contain the value, the bufferis empty.
- ioLen
On input, a pointer to a value of type
UInt32
specifying the length of the buffer pointed to byioBuffer
. On output,ioLen
points to a value that is the length of the valid data inioBuffer
.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid,QTSS_BadIndex
if the index specified byinIndex
does not exist,QTSS_NotEnoughSpace
if the attribute value is longer than the value pointed to byioLen
, andQTSS_AttrDoesntExist
if the attribute doesn’t exist.
Discussion
The
QTSS_GetValue
callback routine copies the value of the specified attribute into the provided buffer.Calling
QTSS_GetValue
is slower and less efficient than callingQTSS_GetValuePtr
.QTSS_GetValueAsString
Gets the value of an attribute as a C string.
QTSS_Error QTSS_GetValueAsString ( QTSS_Object inObject, QTSS_AttributeID inID, UInt32 inIndex, char** outString);
Parameters
- inObject
On input, a value of type
QTSS_Object
specifying the object that contains the attribute whose value is to be obtained.- inID
On input, a value of type
QTSS_AttributeID
specifying the ID of the attribute whose value is to be obtained.- inIndex
On input, a value of type
UInt32
specifying which attribute value to get (if the attribute can have multiple values) or zero for single-value attributes.- outString
On input, a pointer to an address in memory. On output,
outString
points to the value of the attribute specified byinID
in string format.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid, andQTSS_BadIndex
if the index specified byinIndex
does not exist.
Discussion
The
QTSS_GetValueAsString
callback routine gets the value of the specified attribute, converts it to C string format, and stores it at the location in memory pointed to by theoutString
parameter.When you no longer need
outString
, callQTSS_Delete
to free the memory that has been allocated for it.The
QTSS_GetValueAsString
callback routine can be called to get the value of preemptive safe attributes as well as attributes that are not preemptive safe. However, callingQTSS_GetValueAsString
is less efficient than callingQTSS_GetValue
, and callingQTSS_GetValue
is less efficient than callingQTSS_GetValuePtr
.Calling
QTSS_GetValue
is the recommended way to get the value of an attribute that is not preemptive safe and callingQTSS_GetValuePtr
is the recommended way to get the value of an attribute that is preemptive safe.QTSS_GetValuePtr
Gets a pointer to an attribute’s value.
QTSS_Error QTSS_GetValuePtr ( QTSS_Object inObject, QTSS_AttributeID inID, UInt32 inIndex, void** outBuffer, UInt32* outLen);
Parameters
- inObject
On input, a value of type
QTSS_Object
specifying the object containing the attribute whose value is to be obtained.- inID
On input, a value of type
QTSS_AttributeID
specifying the ID of an attribute.- inIndex
On input, a value of type
UInt32
specifying which attribute value to get (if the attribute can have multiple values) or zero for single-value attributes.- outBuffer
On input, a pointer to an address in memory. On output,
outBuffer
points to the value of the attribute.- outLen
On output, a pointer to a value of type
UInt32
specifying the number of valid bytes pointed to byoutBuffer
.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_NotPreemptiveSafe
ifinID
is an attribute that is not preemptive safe,QTSS_BadArgument
if a parameter is invalid,QTSS_BadIndex
if the index specified byinIndex
does not exist, andQTSS_AttrDoesntExist
if the attribute doesn’t exist.
Discussion
The
QTSS_GetValuePtr
callback routine gets a pointer to an attribute’s value. CallingQTSS_GetValuePtr
is the fastest and most efficient way to get the value of an attribute, and it is less likely to generate an error.Before calling
QTSS_GetValuePtr
to get the value of an attribute that is not preemptive safe, you must lock the object by callingQTSS_LockObject
. After getting the value, unlock the object by callingQTSS_UnLockObject
.If you don’t want to lock and unlock the object to get the value of an attribute that is not preemptive safe, get the value by calling
QTSS_GetValue
orQTSS_GetValueAsString
.QTSS_IDForAttr
Gets the ID of a static attribute.
QTSS_Error QTSS_IDForAttr( QTSS_ObjectType inType, const char* inAttributeName, QTSS_AttributeID* outID);
Parameters
- inType
On input, a value of type
QTSS_ObjectType
specifying the type of object for which the ID is to be obtained.- inAttributeName
On input, a pointer to a byte array specifying the name of the attribute whose ID is to be obtained.
- outID
On input, a pointer to a value of type
QTSS_AttributeID
. On output,outID
points to the ID of the attribute specified byinAttributeName
.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_IDForAttr
callback routine obtains the attribute ID for the specified static attribute in the specified object type. The attribute ID is used to when callingQTSS_GetValue
,QTSS_GetValueAsString
, andQTSS_GetValuePtr
get the attribute’s value.To get the ID of an instance attribute, call
QTSS_GetAttrInfoByName
orQTSS_GetAttrInfoByIndex
.QTSS_RemoveInstanceAttribute
Remove an instance attribute from the instance of an object.
QTSS_Error QTSS_RemoveInstanceAttribute( QTSS_Object inObject, QTSS_AttributeID inID);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object from which the instance attribute is to be removed.- inID
On input, a value of type
QTSS_AttributeID
that specifies the ID of the attribute that is to be removed.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_BadArgument
if the specified object instance does not exist, andQTSS_AttrDoesntExist
if the attribute doesn’t exist.
Discussion
The
QTSS_RemoveInstanceAttribute
callback routine removes the attribute specified by theinID
parameter from the instance of an object specified by theinObject
parameter.The
QTSS_RemoveInstanceAttribute
callback can be called from any role.QTSS_RemoveValue
Removes the specified value from an attribute.
QTSS_Error QTSS_RemoveValue ( QTSS_Object inObject, QTSS_AttributeID inID, UInt32 inIndex);
Parameters
- inObject
On input, a value of type
QTSS_Object
having an attribute whose value is to be removed.- inValueLen
On input, a value of type
QTSS_AttributeID
containing the attribute ID of the attribute whose value is to be removed.- inIndex
On input, a value of type
UInt32
that specifies the attribute value that is to be removed. Attribute value indexes are numbered starting from zero.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
ifInObject
,inID
, orinIndex
do not contain valid values,QTSS_ReadOnly
if the attribute is read-only, andQTSS_BadIndex
if the specified index does not exist.
Discussion
The
QTSS_RemoveValue
callback routine removes the value of the specified attribute. After the value is removed, the attribute values are renumbered.QTSS_SetValue
Sets the value of an attribute.
QTSS_Error QTSS_SetValue ( QTSS_Object inObject, QTSS_AttributeID inID, UInt32 inIndex, const void* inBuffer, UInt32 inLen);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object containing the attribute whose value is to be set.- inID
On input, a value of type
QTSS_AttributeID
that specifies the ID of the attribute whose value is to be set.- inIndex
On input, a value of type
UInt32
that specifies which attribute value to set (if the attribute can have multiple values) or zero for single-value attributes.- inBuffer
On input, a pointer to a buffer containing the value that is to be set. When
QTSS_SetValue
returns, you can dispose ofinBuffer
.- inLen
On input, a pointer to a value of type
UInt32
that specifies the length of valid data ininBuffer
.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_BadIndex
if the index specified byinIndex
does not exist,QTSS_BadArgument
if a parameter is invalid,QTSS_ReadOnly
if the attribute is read-only, andQTSS_AttrDoesntExist
if the attribute doesn’t exist.
Discussion
The
QTSS_SetValue
callback routine explicitly sets the value of the specified attribute. Another way to set the value of an attribute is to callQTSS_SetValuePtr
.QTSS_SetValuePtr
Sets an existing variable as the value of an attribute.
QTSS_Error QTSS_SetValue ( QTSS_Object inObject, QTSS_AttributeID inID, const void* inBuffer, UInt32 inLen);
Parameters
- inObject
On input, a value of type
QTSS_Object
that specifies the object containing the attribute whose value is to be set.- inID
On input, a value of type
QTSS_AttributeID
that specifies the ID of the attribute whose value is to be set.- inBuffer
On input, a pointer to a buffer containing the value that is to be set.
- inLen
On input, a pointer to a value of type
UInt32
that specifies the length of valid data ininBuffer
.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid, andQTSS_ReadOnly
if the attribute is a read-only attribute.
Discussion
The
QTSS_SetValuePtr
callback routine allows modules to set an attribute that its value is the value of a module’s variable. This callback is an alternative to theQTSS_SetValue
callback.After calling
QTSS_SetValuePtr
, the module must insure that the buffer pointed to byinBuffer
exists as long as the attribute specified byinID
exists.If the buffer pointed to by
inBuffer
is not updated atomically, updating the value of inBuffer should be protected by callingQTSS_LockObject
before an update.callbackQTSS_StringToValue
Converts an attribute data type in C string format to a value in
QTSS_AttrDataType
format.QTSS_Error QTSS_StringToValue( const char* inValueAsString, const QTSS_AttrDataType inType, void* ioBuffer, UInt32* ioBufSize);
Parameters
- inValueAsString
On input, a pointer to a character array containing the value that is to be converted.
- inType
On input, a value of type
QTSS_AttrDataType
that specifies the attribute data type to which the value pointed to byinValueAsString
is to be converted.- ioBuffer
On input, a pointer to a buffer. On output, the buffer contains the attribute data type to which inValueAsString has been converted. The calling module must allocate
ioBuffer
before callingQTSS_StringToValue
.- ioBufSize
On input, a pointer to a value of type
UInt32 that specifies the length of the buffer pointed to by ioBuffer.
On output,ioBufSize
points to the length of data inioBuffer
.- result
A result code. Possible values are
QTSS_NoErr
,QTSS_BadArgument
ifinValueAsString
orinType
do not contain valid values, andQTSS_NotEnoughSpace
if the buffer pointed to byioBuffer
is too small to contain the converted value.
Discussion
The
QTSS_StringToValue
callback routine converts an attribute data type that is in C string format to a value that is inQTSS_AttrDataType
format.When the memory allocated for the buffer pointed to by
ioBuffer
is no longer needed, you should deallocate the memory.QTSS_TypeStringToType
Gets the attribute data type of a data type string that is in C string format.
QTSS_Error QTSS_TypeStringToType( const char* inTypeString, QTSS_AttrDataType* outType);
Parameters
- inTypeString
On input, a pointer to a character array containing the attribute data type in C string format.
- outType
On output, a pointer to a value of type
QTSS_AttrDataType
containing the attribute data type.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
ifinTypeString
does not contain a value for which an attribute data type can be returned.
Discussion
The
QTSS_TypeStringToType
callback routine gets the attribute data type of a data type string that is in C string format.QTSS_TypeToTypeString
Gets the name in C string format of an attribute data type.
QTSS_Error QTSS_TypeToTypeString( const QTSS_AttrDataType inType, char** outTypeString);
Parameters
- inType
On input, a pointer to a value of type
QTSS_AttrDataType
containing the attribute data type that is to be returned in C string format.- outType
On input, a pointer to an address in memory. On output,
outType
points to a C string containing the attribute data type.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
ifinType
does not contain a valid attribute data type.
Discussion
The
QTSS_TypeToTypeString
callback routine gets the name in C string format of a value that is inQTSS_AttrDataType
format.QTSS_ValueToString
Converts an attribute data type in
QTSS_AttrDataType
format to a value in C string format.QTSS_Error QTSS_ValueToString( const void* inValue, const UInt32 inValueLen, const QTSS_AttrDataType inType, char** outString);
Parameters
- inValue
On input, a pointer to a buffer containing the value that is to be converted from
QTSS_AttrDataType
format.- inValueLen
On input, a value of type
UInt32
that specifies the length of the value pointed to byinValue
.- inType
On input, a value of type
QTSS_AttrDataType
that specifies the attribute data type of the value pointed byinValue
.- outString
On output, a pointer to a location in memory containing the attribute data type in C string format.
- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
ifinValue
,inValueLen
, orinType
do not contain valid values.
Discussion
The
QTSS_ValueToString
callback routine converts an attribute data type inQTSS_AttrDataType
format to a value in C string format.
Stream Callback Routines
This section describes the callback routines that modules call to perform I/O on streams. Internally, the server performs I/O asynchronously, so QTSS stream callback routines do not block and, unless otherwise noted, return the error
QTSS_WouldBlock
if data cannot be written.QTSS_Advis
Advises that the specified section of the stream will soon be read.
QTSS_Error QTSS_Advise( QTSS_StreamRef inRef, UInt64 inPosition, UInt32 inAdviseSize);
Parameters
- inRef
On input, a value of type
QTSS_StreamRef
obtained by callingQTSS_OpenFileObject
that specifies the stream.- inPosition
On input, the offset in bytes from the beginning of the stream that marks the beginning of the advise section.
- inAdviseSize
On input, the size in bytes of the advise section.
- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid, andQTSS_RequestFailed
.
Discussion
The
QTSS_Advise
callback routine tells a file system module that the specified section of a stream will be read soon. The file system module may read ahead in order to respond more quickly to future calls toQTSS_Read
for the specified stream.QTSS_Read
Reads data from a stream.
QTSS_Error QTSS_Read( QTSS_StreamRef inRef, void* ioBuffer, UInt32 inBufLen, UInt32* outLengthRead);
Parameters
- inRef
On input, a value of type
QTSS_StreamRef
that specifies the stream from which data is to be read. CallQTSS_OpenFileObject
to obtain a stream reference for the file you want to read.- ioBuffer
On input, a pointer to a buffer in which data that is read is to be placed.
- inBufLen
On input, a value of type
UInt32
that specifies the length of the buffer pointed to byioBuffer
.- outLenRead
On output, a pointer to a value of type
UInt32
that contains the number of bytes that were read.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid,QTSS_WouldBlock
if the read operation would block, orQTSS_RequestFailed
if the read operation failed.
Discussion
The
QTSS_Read
callback routine reads a buffer of data from a stream.QTSS_Seek
Sets the position of a stream.
QTSS_Error QTSS_Seek( QTSS_StreamRef inRef, UInt64 inNewPosition);
Parameters
- inRef
On input, a value of type
QTSS_StreamRef
QTSS_StreamRef
that specifies the stream whose position is to be set. CallQTSS_OpenFileObject
to obtain stream reference.- inNewPosition
On input, the offset in bytes from the start of the stream to which the position is to be set.
- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid, andQTSS_RequestFailed
if the seek operation failed.
Discussion
The
QTSS_Seek
callback routine sets the stream position to the value specified byinNewPosition
.QTSS_RequestEvent
Requests notification of specified events.
QTSS_Error QTSS_RequestEvent( QTSS_StreamRef inStream, QTSS_EventType inEventMask);
Parameters
- inStream
On input, a value of type
QTSS_StreamRef
that specifies the stream for which event notifications are requested.- inEventMask
On input, a value of type
QTSS_EventType
specifying a mask that represents the events for which notifications are requested.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid, andQTSS_RequestFailed
if the call failed.
Discussion
The
QTSS_RequestEvent
callback requests that the caller be notified when the specified events occur on the specified stream. After callingQTSS_RequestEvent
, the calling module should return as soon as possible from its current module role. The server preserves the calling module’s current state and, when the event occurs, calls the module in the role the module was in when it calledQTSS_RequestEvent
.QTSS_SignalStream
Notifies the recipient of events that a stream has become available for I/O.
QTSS_Error QTSS_RequestEvent( QTSS_StreamRef inStream, QTSS_EventType inEventMask);
Parameters
- inStream
On input, a value of type
QTSS_StreamRef
specifying the stream that has become available for I/O.- inEventMask
On input, a value of type
QTSS_EventType
containing a mask that represents whether the stream has become available for reading, writing, or both.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid,QTSS_OutOfState
if this callback is made from a role that does not allow asynchronous events, andQTSS_RequestFailed
if the call failed.
Discussion
The
QTSS_SignalStream
callback routine tells the server that the stream represented by inStream has become available for I/O. Currently only file system modules have reason to callQTSS_SignalStream
.QTSS_Write
Writes data to a stream.
QTSS_Error QTSS_Write( QTSS_StreamRef inRef, void* inBuffer, UInt32 inLen, UInt32* outLenWritten, UInt32 inFlags);
Parameters
- inRef
On input, a value of type
QTSS_StreamRef
that specifies the stream to which data is to be written.- inBuffer
On input, a pointer to a buffer containing the data that is to be written.
- inLen
On input, a value of type
UInt32
that specifies the length of the data in the buffer pointed to byioBuffer
.- outLenWritten
On output, a pointer to a value of type
UInt32
that contains the number of bytes that were written.- inFlags
On input, a value of type
UInt32
. See the Discussion section for possible values.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid,QTSS_NotConnected
if the stream receiver is no longer connected, andQTSS_WouldBlock
if the stream cannot be completely flushed at this time.
Discussion
The
QTSS_Write
callback routine writes a buffer of data to a stream.The following enumeration defines constants for the
inFlags
parameter:enum
{
qtssWriteFlagsIsRTP = 0x00000001,
qtssWriteFlagsIsRTCP= 0x00000002
};
These flags are relevant when writing to an RTP stream reference and tell the server whether the data written should be sent over the RTP channel (
qtssWriteFlagsIsRTP
) or over the RTCP channel of the specified RTP stream (qtssWriteFlagsIsRTCP
).QTSS_WriteV
Writes data to a stream using an iovec structure.
QTSS_Error QTSS_WriteV( QTSS_StreamRef inRef, iovec* inVec, UInt32 inNumVectors, UInt32 inTotalLength, UInt32* outLenWritten);
Parameters
- inRef
On input, a value of type
QTSS_StreamRef
that specifies the stream to which data is to be written.- inVec
On input, a pointer to an
iovec
structure. The first member of theiovec
structure must be empty.- inNumVectors
On input, a value of type
UInt32
that specifies the number of vectors.- inTotalLength
On input, a value of type
UInt32
specifying the total length ofinVec
.- outLenWritten
On output, a pointer to a value of type
UInt32
containing the number of bytes that were written.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter isNULL
, andQTSS_WouldBlock
if the write operation would block.
Discussion
The
QTSS_WriteV
callback routine writes a data to a stream using aniovec
structure in a way that is similar to the POSIXwritev
call.QTSS_Flush
Forces an immediate write operation.
QTSS_Error QTSS_Flush(QTSS_StreamRef inRef);
Parameters
- inRef
On input, a value of type
QTSS_StreamRef
that specifies the stream for which buffered data is to be written.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter isNULL
, andQTSS_WouldBlock
if the stream cannot be flushed completely at this time.
Discussion
The
QTSS_Flush
callback routine forces the stream to immediately write any data that has been buffered. Some QTSS stream references, such asQTSSRequestRef
, buffer data before sending it.
File System Callback Routines
Modules use the callback routines described in this section to open and close a file object.
QTSS_OpenFileObject
Opens a file.
QTSS_Error QTSS_OpenFileObject( char* inPath, QTSS_OpenFileFlags inFlags, QTSS_Object* outFileObject);
Parameters
- inPath
On input, a pointer to a null-terminated C string containing the full path to the file in the local file system that is to be opened.
- inFlags
On input, a value of type
QTSS_OpenFileFlags
specifying flags that describe how the file is to be opened.
- outFileObject
On output, a pointer to a value of type
QTSS_Object
in which the file object for the opened file is to be placed.- result
A result code. Possible values include
QTSS_NoErr
,QTSS_BadArgument
if a parameter is invalid, andQTSS_FileNotFound
if the specified file does not exist.
Discussion
The
QTSS_OpenFileObject
callback routine opens the specified file and returns a file object for it. One of the attributes of the file object is a stream reference that is passed to QTSS stream callback routines to read and write data to the file and to perform other file operations.QTSS_CloseFileObject
Closes a file.
QTSS_Error QTSS_CloseFileObject(QTSS_Object inFileObject);
Parameters
- inFileObject
On input, a value of type
QTSS_Object
that represents the file that is to be closed.- result
A result code. Possible values include
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_CloseFileObject
callback routine closes the specified file.
Service Callback Routines
Modules use the callback routines described in this section to register and invoke services.
QTSS_AddService
Adds a service.
QTSS_Error QTSS_AddService( const char* inServiceName, QTSS_ServiceFunctionPtr inFunctionPtr);
Parameters
- inServiceName
On input, a pointer to a string containing the name of the service that is being added.
- inFunctionPtr
On input, a pointer to the module that provides the service that is being added.
- result
A result code. Possible values include
QTSS_NoErr
,QTSS_OutOfState
ifQTSS_AddService
is not called from the Register role, andQTSS_BadArgument
ifinServiceName
is too long or if a parameter isNULL
.
Discussion
The
QTSS_AddService
callback routine makes the specified service available for other modules to call.This callback can only be called from the Register role.
QTSS_IDForService
Resolves a service name to a service ID.
QTSS_Error QTSS_IDForService( const char* inTag, QTSS_ServiceID* outID);
Parameters
- inTag
On input, a pointer to a string containing the name of the service that is to be resolved.
- outID
On input, a pointer to a value of type
QTSS_ServiceID
. On output,QTSS_ServiceID
contains the ID of the service specified byinTag
.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_IDForService
callback routine returns in theoutID
parameter the service ID of the service specified by theinTag
parameter. You can use the service ID to callQTSS_DoService
to invoke the service thatserviceID
represents.QTSS_DoService
Invokes a service.
QTSS_Error QTSS_DoService( QTSS_ServiceID inID, QTSS_ServiceFunctionArgsPtr inArgs);
Parameters
- inID
On input, a value of type
QTSS_ServiceID
that specifies the service that is to be invoked. CallQTSS_IDForAttr
to get the service ID of the service you want to invoke.- inArgs
On input, a value of type
QTSS_ServiceFunctionArgsPtr
that points to the arguments that are to be passed to the service.- result
A result code returned by the service or
QTSS_IllegalService
ifinID
is invalid.
Discussion
The
QTSS_DoService
callback routine invokes the service specified byinID
.
RTSP Header Callback Routines
As a convenience to modules that want to send RTSP responses, the server provides the utilities described in this section for formatting RTSP responses properly.
QTSS_AppendRTSPHeader
Appends information to an RTSP header.
QTSS_Error QTSS_AppendRTSPHeader( QTSS_RTSPRequestObject inRef, QTSS_RTSPHeader inHeader, const char* inValue, UInt32 inValueLen);
Parameters
- inRef
On input, a value of type
QTSS_RTSPRequestObject
for the RTSP stream.- inHeader
On input, a value of type
QTSS_RTSPHeader
.- inValue
On input, a pointer to a byte array containing the header that is to be appended.
- inValueLen
On input, a value of type
UInt32
containing the length of valid data pointed to byinValue
.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_AppendRTSPHeader
callback routine appends headers to an RTSP header. After callingQTSS_AppendRTSPHeader
, callQTSS_SendRTSPHeaders
to send the entire header.QTSS_SendRTSPHeaders
Sends an RTSP header.
QTSS_Error QTSS_SendRTSPHeaders(QTSS_RTSPRequestOjbect inRef);
Parameters
- inRef
On input, a value of type QTSS_RTSPRequestObject for the RTSP stream.
- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_SendRTSPHeaders
callback routine sends an RTSP header. When a module callsQTSS_SendRTSPHeaders
, the server sends a proper RTSP status line, using the request’s current status code. The server also sends the properCSeq
header, session ID header, and connection header.-
QTSS_SendStandardRTSPResponse
Sends an RTSP response to a client.
QTSS_Error QTSS_SendStandardRTSPResponse( QTSS_RTSPRequestObject inRTSPRequest, QTSS_Object inRTPInfo, UInt32 inFlags);
Parameters
- inRTSPRequest
On input, a value of type QTSS_RTSPRequestObject for the RTSP stream.
- inRTPInfo
On input, a value of type
QTSS_Object
. This parameter is aQTSS_ClientSessionObject
or aQTSS_RTPStreamObject
, depending the response that is sent.- inFlags
On input, a value of type
UInt32
. SetinFlags
toqtssPlayRespWriteTrackInfo
if you want the server to append the seq number, a timestamp, and SSRC information to RTP-Info headers.- result
A result code. Possible values include
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_SendStandardRTSPResponse
callback routine writes a standard response to the stream specified by the inRTSPRequest parameter. The actual response that is sent depends on the method.The following enumeration defines the
qtssPlayRespWriteTrackInfo
constant for theinFlags
parameter:enum
{
qtssPlayRespWriteTrackInfo = 0x00000001
};
This function supports the following response methods:
DESCRIBE. This response method writes status line, CSeq, SessionID, Connection headers as determined by the request. Writes a Content-Base header with the content base being the URL provided. Writes a Content-Type header of
application/sdp
. TheinRTPInfo
parameter must be aQTSS_ClientSessionObject
.ANNOUNCE. This response method writes status line, CSeq, and Connection headers as determined by the request. The
inRTPInfo
parameter must be aQTSS_ClientSessionObject
.SETUP. This response method writes status line, CSeq, SessionID, Connection headers as determined by the request. Writes a Transport header with client and server ports (if the connection is over UDP). The
inRTPInfo
parameter must be aQTSS_RTPStreamObject
.PLAY. This response method writes status line, CSeq, SessionID, Connection headers as determined by the request. The
inRTPInfo
parameter must be aQTSS_ClientSessionObject
. Set theinFlags
parameter toqtssPlayRespWriteTrackInfo
to specify that you want the server to append the sequence number, timestamp, and SSRC information to the RTP-Info header.PAUSE. This response method writes status line, CSeq, SessionID, Connection headers as determined by the request. The
inRTPInfo
parameter must be aQTSS_ClientSessionObject
.TEARDOWN. This response method writes status line, CSeq, SessionID, Connection headers as determined by the request. The
inRTPInfo
parameter must be aQTSS_ClientSessionObject
.
RTP Callback Routines
QTSS modules can generate and send RTP packets in response to an RTSP request. Typically RTP packets are sent in response to a SETUP request from the client. Currently, only one module can generate packets for a particular session.
QTSS_AddRTPStream
Enables a module to send RTP packets to a client.
QTSS_Error QTSS_AddRTPStream( QTSS_ClientSessionObject inClientSession, QTSS_RTSPRequestObject inRTSPRequest, QTSS_RTPStreamObject* outStream, QTSS_AddStreamFlags inFlags);
Parameters
- inClientRequest
On input, a value of type
QTSS_ClientSessionObject
identifying the client session for which the sending of RTP packets is to be enabled.- inRTSPRequest
On input, a value of type
QTSS_RTSPRequestObject
.- outStream
On output, a pointer to a value of type
QTSS_RTPStreamObject
, containing the newly created stream.- inFlags
On input, a value of type
QTSS_AddStreamFlags
that specifies stream options.- result
A result code. Possible values are
QTSS_NoErr, QTSS_RequestFailed
if theQTSS_RTPSteamObject
couldn’t be created, andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_AddRTSPStream
callback routine enables a module to send RTP packets to a client in response to an RTSP request. CallQTSS_AddRTSPStream
multiple times in order to add more than one stream to the session.To start playing a stream, call
QTSS_Play
.QTSS_Play
Starts playing streams associated with a client session.
QTSS_Error QTSS_Play( QTSS_ClientSessionObject inClientSession, QTSS_RTSPRequestObject inRTSPRequest, QTSS_PlayFlags inPlayFlags);
Parameters
- inClientSession
On input, a value of type QTSS_ClientSessionObject that identifies the client session for which the sending of RTP packets was enabled by previously calling
QTSS_AddRTPStream
.- inRTSPRequest
On input, a value of type
QTSS_RequestObject
.- inPlayFlags
On input, a value of type
QTSS_PlayFlags
. SetinPlayFlags
to the constantqtssPlaySendRTCP
to cause the server to generate RTCP sender reports automatically while playing. Otherwise, the module is responsible for generating sender reports that specify play characteristics.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid, andQTSS_RequestFailed
if no streams have been added to the session.
Discussion
The
QTSS_Play
callback routine starts playing streams associated with the specified client session.The module that called
QTSS_AddRTPStream
is the only module that can callQTSS_Play
.Before calling
QTSS_Play
, the module should set the following attributes of theQTSS_RTPStreamObject
object for this RTP stream:qtssRTPStrFirstSeqNumber
, which should be set to the sequence number of the first packet after the last PLAY request was issued. The server uses the sequence number to generate a proper RTSP PLAY response.qtssRTPStrFirstTimestamp
, which should be set to the timestamp of the first RTP packet generated for this stream after the last PLAY request was issued. The server uses the timestamp to generate a proper RTSP PLAY response.qtssRTPStrTimescale
, which should be set to the timescale for the track.
After calling
QTSS_Play
, the module is invoked in the RTP Send Packets role.Call
QTSS_Pause
to pause playing or callQTSS_Teardown
to close the client session.QTSS_Pause
Pauses a stream that is playing.
QTSS_Error QTSS_Pause(QTSS_ClientSessionObject inClientSession);
Parameters
- inClientSession
On input, a value of type
QTSS_ClientSessionObject
that identifies the client session that is to be paused.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_Pause
callback routine pauses playing for a stream. The module that calledQTSS_AddRTPStream
is the only module that can callQTSS_Pause
.QTSS_Teardown
Closes a client session.
QTSS_Error QTSS_Teardown(QTSS_ClientSessionObject inClientSession);
Parameters
- inClientSession
On input, a value of type
QTSS_ClientSessionObject
that identifies the client session that is to be closed.- result
A result code. Possible values are
QTSS_NoErr
andQTSS_BadArgument
if a parameter is invalid.
Discussion
The
QTSS_Teardown
callback routine closes a client session.The module that called
QTSS_AddRTPStream
is the only module that can callQTSS_Teardown
.Calling
QTSS_Teardown
causes the calling module to be invoked in the Client Session Closing role for the session identified by theinClientSession
parameter.
Copyright © 2002, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-06-01