QuickTime Streaming Server Modules Programming Guide 2005-04-29 Simultaneously published in the United Apple Computer, Inc. States and Canada. © 2002, 2005 Apple Computer, Inc. Even though Apple has reviewed this document, All rights reserved. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS No part of this publication may be DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A reproduced, stored in a retrieval system, or PARTICULAR PURPOSE. AS A RESULT, THIS transmitted, in any form or by any means, DOCUMENT IS PROVIDED “AS IS,” AND mechanical, electronic, photocopying, YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND recording, or otherwise, without prior ACCURACY. written permission of Apple Computer, Inc., IN NO EVENT WILL APPLE BE LIABLE FOR with the following exceptions: Any person DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES is hereby authorized to store documentation RESULTING FROM ANY DEFECT OR on a single computer for personal use only INACCURACY IN THIS DOCUMENT, even if and to print copies of documentation for advised of the possibility of such damages. personal use provided that the THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN documentation contains Apple’s copyright LIEU OF ALL OTHERS, ORAL OR WRITTEN, notice. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any The Apple logo is a trademark of Apple modification, extension, or addition to this Computer, Inc. warranty. Some states do not allow the exclusion or Use of the “keyboard” Apple logo limitation of implied warranties or liability for (Option-Shift-K) for commercial purposes incidental or consequential damages, so the above limitation or exclusion may not apply to without the prior written consent of Apple you. This warranty gives you specific legal may constitute trademark infringement and rights, and you may also have other rights which vary from state to state. unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Mac, Mac OS, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. QuickTime Broadcaster is a trademark of Apple Computer, Inc. Times is a registered trademark of Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. Contents Introduction About This Manual 11 What’s New 11 Conventions Used in This Manual 12 For More Information 12 Chapter 1 Concepts 15 Server Architecture 16 Modules 17 Protocols 18 Data 19 Classes 19 Applications and Tools 20 Source Organization 21 Server Preference Naming 23 Requirements for Modules 24 Main Routine 24 Dispatch Routine 25 Overview of QuickTime Streaming Server Operations 25 Server Startup and Shutdown 25 RTSP Request Processing 26 Runtime Environment for QTSS Modules 30 Server Time 31 Naming Conventions 31 Module Roles 32 Register Role 33 Initialize Role 33 Shutdown Role 34 Reread Preferences Role 35 Error Log Role 35 RTSP Roles 36 RTP Roles 41 RTCP Process Role 42 QTSS Objects 43 qtssAttrInfoObjectType 44 qtssClientSessionObjectType 44 qtssConnectedUserObjectType 47 3 2005-04-29 | © 2002, 2005 Apple Computer, Inc. All Rights Reserved. CONTENTS qtssDynamicObjectType 48 qtssFileObjectType 48 qttsModuleObjectType 49 qtssModulePrefsObjectType 50 qtssPrefsObjectType 58 qtssRTPStreamObjectType 69 qtssRTSPHeaderObjectType 72 qtssRTSPRequestObjectType 72 qtssRTSPSessionObjectType 75 qtssServerObjectType 76 qtssTextMessageObjectType 79 qtssUserProfileObjectType 82 QTSS Streams 82 QTSS Services 84 Built-in Services 85 Automatic Broadcasting 86 Automatic Broadcasting Scenarios 86 ANNOUNCE Requests and SDP 87 Access Control of Announced Broadcasts 88 Broadcaster-to-Server Example 89 Additional Trace Examples 91 Stream Caching 98 Speed RTSP Header 98 x-Transport-Options Header 99 RTP Payload Meta-Information 100 x-Packet-Range RTSP Header 105 Reliable UDP 106 Acknowledgment Packets 106 RTSP Negotiation 107 Tunneling RTSP and RTP Over HTTP 107 HTTP Client Request Requirements 108 HTTP Server Reply Requirements 109 RTSP Request Encoding 110 Connection Maintenance 111 Support For Other HTTP Features 111 Chapter 2 Tasks 113 Building the Streaming Server 113 Mac OS X 113 POSIX 113 Windows 114 Building a QuickTime Streaming Server Module 114 Compiling a QTSS Module into the Server 114 Building a QTSS Module as a Code Fragment 114 Debugging 115 4 2005-04-29 | © 2002, 2005 Apple Computer, Inc. All Rights Reserved. CONTENTS RTSP and RTP Debugging 115 Source File Debugging Support 115 Working with Attributes 116 Getting Attribute Values 117 Setting Attribute Values 118 Adding Attributes 119 Using Files 120 Reading Files Using Callback Routines 121 Implementing a QTSS File System Module 122 Using the Admin Protocol 130 Access to Server Data 130 Request Syntax 130 Request Functionality 131 Data References 131 Request Options 132 Command Options 132 Attribute Access Types 134 Data Types 134 Server Responses 134 Changing Server Settings 139 Getting and Setting Preferences 139 Getting and Changing the Server’s State 140 Chapter 3 QTSS Callback Routines 141 Callbacks by Task 141 QTSS Utility Callback Routines 141 QTSS Object Callback Routines 141 QTSS Attribute Callback Routines 142 Stream Callback Routines 143 File System Callback Routines 143 Service Callback Routines 143 RTSP Header Callback Routines 144 RTP Callback Routines 144 Callbacks 144 QTSS_AddInstanceAttribute 144 QTSS_AddRole 146 QTSS_AddRTPStream 146 QTSS_AddService 147 QTSS_AddStaticAttribute 147 QTSS_Advis 148 QTSS_AppendRTSPHeader 149 QTSS_CloseFileObject 150 QTSS_CreateObjectType 150 QTSS_CreateObjectValue 150 QTSS_Delete 151 5 2005-04-29 | © 2002, 2005 Apple Computer, Inc. All Rights Reserved. CONTENTS QTSS_DoService 152 QTSS_Flush 152 QTSS_GetAttrInfoByID 152 QTSS_GetAttrInfoByIndex 153 QTSS_GetAttrInfoByName 154 QTSS_GetNumAttributes 154 QTSS_GetValue 155 QTSS_GetValueAsString 156 QTSS_GetValuePtr 157 QTSS_IDForAttr 158 QTSS_IDForService 158 QTSS_LockObject 159 QTSS_Milliseconds 159 QTSS_MilliSecsTo1970Secs 160 QTSS_New 160 QTSS_OpenFileObject 161 QTSS_Pause 161 QTSS_Play 162 QTSS_Read 162 QTSS_RemoveInstanceAttribute 163 QTSS_RemoveValue 164 QTSS_RequestEvent 164 QTSS_Seek 165 QTSS_SendRTSPHeaders 165 QTSS_SendStandardRTSPResponse 166 QTSS_SetValue 167 QTSS_SetValuePtr 168 QTSS_SignalStream 168 QTSS_StringToValue 169 QTSS_Teardown 170 QTSS_TypeStringToType 170 QTSS_TypeToTypeString 171 QTSS_UnLockObject 171 QTSS_ValueToString 172 QTSS_Write 172 QTSS_WriteV 173 Chapter 4 QTSS Data Types 175 QTSS_AttributeID 175 QTSS_Object 175 QTSS_ObjectType 175 QTSS_Role 176 QTSS_ServiceID 176 QTSS_StreamRef 177 QTSS_TimeVal 177 6 2005-04-29 | © 2002, 2005 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 5 QTSS Constants 179 QTSS_AttrDataType 179 QTSS_AttrPermission 180 QTSS_AddStreamFlags 181 QTSS_CliSesTeardownReason 181 QTSS_EventType 181 QTSS_OpenFileFlags 182 QTSS_RTPPayloadType 182 QTSS_RTPNetworkMode 183 QTSS_RTPSessionState 183 QTSS_RTPTransportType 183 QTSS_RTSPSessionType 184 QTSS_ServerState 184 Document Revision History 187 Index 189 7 2005-04-29 | © 2002, 2005 Apple Computer, Inc. All Rights Reserved. CONTENTS 8 2005-04-29 | © 2002, 2005 Apple Computer, Inc. All Rights Reserved. Figures, Tables, and Listings Chapter 1 Concepts 15 Figure 1-1 Server architecture 16 Figure 1-2 Server object data model 19 Figure 1-3 QuickTime Streaming Server startup and shutdown 26 Figure 1-4 Sample RTSP request 27 Figure 1-5 Summary of RTSP request processing 28 Figure 1-6 Summary of the RTSP Preprocessor and RTSP Request roles 30 Figure 1-7 Pull-then-push automatic broadcasting 86 Figure 1-8 Listen-then-push automatic broadcasting 87 Figure 1-9 Standard RTP payload meta-information format 102 Figure 1-10 RTP data in standard format 103 Figure 1-11 Compressed RTP payload meta-information format 104 Figure 1-12 Mixed RTP payload meta-information format 104 Figure 1-13 Reliable UDP acknowledgment packet format 107 Figure 1-14 Required connections for tunneling 108 Table 1-1 Module roles 32 Table 1-2 Attributes of objects of type qtssAttrInfoObjectType 44 Table 1-3 Attributes of objects of type qtssClientSessionObjectType 45 Table 1-4 Attributes of objects of type qtssConnectedUserObjectType 47 Table 1-5 Attributes of objects of type qtssFileObjectType 48 Table 1-6 Attributes of objects of type qtssModuleObjectType 49 Table 1-7 Attributes for preferences of the module QTSSAccessLogModule 50 Table 1-8 Attributes for preferences of the module QTSSAccessModule 51 Table 1-9 Attributes for preferences of the module QTSSAdminModule 51 Table 1-10 Attributes for preferences of the module QTSSFileModule 52 Table 1-11 Attributes for preferences of the module QTSSFlowControlModule 53 Table 1-12 Attributes for preferences of the module QTSSHomeDirectoryModule 54 Table 1-13 Attributes for preferences of the module QTSSMP3StreamingModule 54 Table 1-14 Attributes for preferences of the module QTSSReflectorModule