IrDA Object Exchange Protocol
`IrOBEX
`
`Counterpoint Systems Foundry, IncMicrosoft CorporationMarch 18, 1999Version 1.2
`
`1
`
`LG 1006
`
`

`

`Object Exchange ProtocolVersion 1.22
`
`1.2Major changes from Version 1.1 draft to 1.2:• Incorporate the OBEX Errata approved at the January 1999 IrDA meeting.
`• Incorporate the OBEX Errata approved in March of 1999.Major changes from Version 1.0 to 1.1 draft:• Incorporate the “OBEX Errata v.3” approved at the July 1997 IrDA meeting.
`
`Document Status: Version
`
`• Incorporate the OBEX Errata approved at the October 1997 IrDA meeting.
`• Incorporate the “IrOBEX Test Guidelines” approved at the October 1998 IrDA meeting.
`
`Authors:
`
`Contributors:
`
`Wassef Haroun, Bei-jing Guo, Cliff Strom (Microsoft)Kerry Lynn (Apple)Brian McBride, Stuart Williams (Hewlett Packard)Petri Nykanen (Nokia)Deepak Amin (Indicus)
`
`Editors:
`
`Pat Megowan, Dave Suvak, Doug Kogan (Counterpoint Systems Foundry)
`Doug Kogan
`

`

`INFRARED DATA ASSOCIATION (IrDA) - NOTICE TO THE TRADE -
`
`SUMMARY
`
`:Following is the notice of conditions and understandings upon which this document is made available to membersand non-members of the Infrared Data Association.
`
`• Availability of Publications, Updates and Notices
`• Full Copyright Claims Must be Honored
`• Controlled Distribution Privileges for IrDA Members Only
`• Trademarks of IrDA - Prohibitions and Authorized Use
`• No Representation of Third Party Rights
`• Limitation of Liability
`• Disclaimer of Warranty
`• Certification of Products Requires Specific Authorization from IrDA after Product Testing for IrDA SpecificationConformance
`
`IrDA PUBLICATIONS and UPDATES
`
`COPYRIGHT
`
`Object Exchange ProtocolVersion 1.23
`
`:IrDA publications, including notifications, updates, and revisions, are accessed electronically by IrDA members ingood standing during the course of each year as a benefit of annual IrDA membership. Electronic copies areavailable to the public on the IrDA web site located at irda.org. IrDA publications are available to non-IrDAmembers for a pre-paid fee. Requests for publications, membership applications or more information should beaddressed to: Infrared Data Association, P.O. Box 3883, Walnut Creek, California, U.S.A. 94598; or e-mailaddress: info@irda.org; or by calling John LaRoche at (510) 943-6546 or faxing requests to (510) 934-5600.
`:1.Prohibitions: IrDA claims copyright in all IrDA publications. Any unauthorized reproduction, distribution, display ormodification, in whole or in part, is strictly prohibited.2.Authorized Use: Any authorized use of IrDA publications (in whole or in part) is under NONEXCLUSIVE USE LICENSEONLY. No rights to sublicense, assign or transfer the license are granted and any attempt to do so is void.
`:IrDA Members Limited Reproduction and Distribution Privilege: A limited privilege of reproduction and distribution ofIrDA copyrighted publications is granted to IrDA members in good standing and for sole purpose of reasonablereproduction and distribution to non-IrDA members who are engaged by contract with an IrDA member for thedevelopment of IrDA certified products. Reproduction and distribution by the non-IrDA member is strictly prohibited.
`
`DISTRIBUTION PRIVILEGES for IrDA MEMBERS ONLY
`
`TRANSACTION NOTICE to IrDA MEMBERS ONLY
`
`:Each and every copy made for distribution under the limited reproduction and distribution privilege shall beconspicuously marked with the name of the IrDA member and the name of the receiving party. Upon reproductionfor distribution, the distributing IrDA member shall promptly notify IrDA (in writing or by e-mail) of the identity of thereceiving party.A failure to comply with the notification requirement to IrDA shall render the reproduction and distributionunauthorized and IrDA may take appropriate action to enforce its copyright, including but not limited to, thetermination of the limited reproduction and distribution privilege and IrDA membership of the non-complyingmember.
`
`TRADEMARKS
`
`:
`

`

`NO REPRESENTATION of THIRD PARTY RIGHTS
`
`LIMITATION of LIABILITY
`
`DISCLAIMER of WARRANTY
`
`Object Exchange ProtocolVersion 1.241.Prohibitions: IrDA claims exclusive rights in its trade names, trademarks, service marks, collective membership marks andcertification marks (hereinafter collectively "trademarks"), including but not limited to the following trademarks: INFRAREDDATA ASSOCIATION (wordmark alone and with IR logo), IrDA (acronym mark alone and with IR logo), IR logo, IR DATACERTIFIED (composite mark), and MEMBER IrDA (wordmark alone and with IR logo). Any unauthorized use of IrDAtrademarks is strictly prohibited.2.Authorized Use: Any authorized use of a IrDA collective membership mark or certification mark is by NONEXCLUSIVEUSE LICENSE ONLY. No rights to sublicense, assign or transfer the license are granted and any attempt to do so is void.
`
`:IrDA makes no representation or warranty whatsoever with regard to IrDA member or third party ownership,licensing or infringement/non-infringement of intellectual property rights. Each recipient of IrDA publications,whether or not an IrDA member, should seek the independent advice of legal counsel with regard to any possibleviolation of third party rights arising out of the use, attempted use, reproduction, distribution or public display ofIrDA publications.IrDA assumes no obligation or responsibility whatsoever to advise its members or non-members who receive or areabout to receive IrDA publications of the chance of infringement or violation of any right of an IrDA member or thirdparty arising out of the use, attempted use, reproduction, distribution or display of IrDA publications.
`:BY ANY ACTUAL OR ATTEMPTED USE, REPRODUCTION, DISTRIBUTION OR PUBLIC DISPLAY OF ANY IrDAPUBLICATION, ANY PARTICIPANT IN SUCH REAL OR ATTEMPTED ACTS, WHETHER OR NOT A MEMBEROF IrDA, AGREES TO ASSUME ANY AND ALL RISK ASSOCIATED WITH SUCH ACTS, INCLUDING BUT NOTLIMITED TO LOST PROFITS, LOST SAVINGS, OR OTHER CONSEQUENTIAL, SPECIAL, INCIDENTAL ORPUNITIVE DAMAGES. IrDA SHALL HAVE NO LIABILITY WHATSOEVER FOR SUCH ACTS NOR FOR THECONTENT, ACCURACY OR LEVEL OF ISSUE OF AN IrDA PUBLICATION.
`:All IrDA publications are provided "AS IS" and without warranty of any kind. IrDA (and each of its members, whollyand collectively, hereinafter "IrDA") EXPRESSLY DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR APARTICULAR PURPOSE AND WARRANTY OF NON-INFRINGEMENT OF INTELLECTUAL PROPERTY RIGHTS.IrDA DOES NOT WARRANT THAT ITS PUBLICATIONS WILL MEET YOUR REQUIREMENTS OR THAT ANYUSE OF A PUBLICATION WILL BE UN-INTERRUPTED OR ERROR FREE, OR THAT DEFECTS WILL BECORRECTED. FURTHERMORE, IrDA DOES NOT WARRANT OR MAKE ANY REPRESENTATIONSREGARDING USE OR THE RESULTS OR THE USE OF IrDA PUBLICATIONS IN TERMS OF THEIRCORRECTNESS, ACCURACY, RELIABILITY, OR OTHERWISE. NO ORAL OR WRITTEN PUBLICATION ORADVICE OF A REPRESENTATIVE (OR MEMBER) OF IrDA SHALL CREATE A WARRANTY OR IN ANY WAYINCREASE THE SCOPE OF THIS WARRANTY.
`:IrDA warrants ONLY the media upon which any publication is recorded to be free from defects in materials andworkmanship under normal use for a period of ninety (90) days from the date of distribution as evidenced by thedistribution records of IrDA. IrDA's entire liability and recipient's exclusive remedy will be replacement of the medianot meeting this limited warranty and which is returned to IrDA. IrDA shall have no responsibility to replace mediadamaged by accident, abuse or misapplication. ANY IMPLIED WARRANTIES ON THE MEDIA, INCLUDING THEIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE LIMITEDIN DURATION TO NINETY (90) DAYS FROM THE DATE OF DELIVERY. THIS WARRANTY GIVES YOUSPECIFIC LEGAL RIGHTS, AND YOU MAY ALSO HAVE OTHER RIGHTS WHICH VARY FROM PLACE TOPLACE.
`
`LIMITED MEDIA WARRANTY
`
`CERTIFICATION and GENERAL
`
`:
`

`

`Object Exchange ProtocolVersion 1.25Membership in IrDA or use of IrDA publications does NOT constitute IrDA compliance. It is the sole responsibility ofeach manufacturer, whether or not an IrDA member, to obtain product compliance in accordance with IrDA rules forcompliance.All rights, prohibitions of right, agreements and terms and conditions regarding use of IrDA publications and IrDArules for compliance of products are governed by the laws and regulations of the United States. However, eachmanufacturer is solely responsible for compliance with the import/export laws of the countries in which they conductbusiness. The information contained in this document is provided as is and is subject to change without notice.
`
`

`

`Contents
`
`1.
`
`INTRODUCTION .................................................................................................................... 9
`
`1.1
`1.2
`
`Tasks, Platforms, and Goals ......................................................................................... 9
`OBEX components....................................................................................................... 10
`
`1.2.1OBEX Session Protocol...........................................................................................101.2.2OBEX Application Framework.................................................................................11
`1.3
`Relation to other IrDA protocols ................................................................................. 12
`1.4
`Specification versus Implementation ......................................................................... 12
`
`1.5
`
`References.................................................................................................................... 13
`
`2. OBEX OBJECT MODEL....................................................................................................... 14
`
`2.1
`2.2
`
`OBEX Headers.............................................................................................................. 14
`Header descriptions..................................................................................................... 15
`
`3. SESSION PROTOCOL......................................................................................................... 20
`
`3.1
`3.2
`
`3.3
`
`Request format............................................................................................................. 21
`Response format.......................................................................................................... 21
`
`OBEX Operations and Opcode definitions................................................................. 23
`
`3.3.1Connect...................................................................................................................233.3.2Disconnect..............................................................................................................263.3.3Put..........................................................................................................................273.3.4Get..........................................................................................................................293.3.5Abort.......................................................................................................................303.3.6SetPath...................................................................................................................30
`
`Packet Timeouts........................................................................................................... 31
`Authentication Procedure............................................................................................ 31
`
`3.4
`3.5
`
`2.2.1Count......................................................................................................................152.2.2Name......................................................................................................................152.2.3Type........................................................................................................................162.2.4Length.....................................................................................................................162.2.5Time........................................................................................................................162.2.6Description..............................................................................................................162.2.7Target.....................................................................................................................172.2.8HTTP......................................................................................................................172.2.9Body, End-of-Body..................................................................................................172.2.10Who........................................................................................................................172.2.11Connection Identifier...............................................................................................182.2.12Application Request-Response Parameters.............................................................182.2.13Authenticate Challenge...........................................................................................192.2.14Authenticate Response............................................................................................192.2.15Object Class............................................................................................................192.2.16User Defined Headers.............................................................................................19
`
`Object Exchange ProtocolVersion 1.26
`
`3.5.1Digest Challenge.....................................................................................................323.5.2Digest Response.....................................................................................................343.5.3Hashing Function....................................................................................................353.5.4Authentication Examples.........................................................................................35
`
`Multiplexing with OBEX............................................................................................... 37
`
`3.6
`
`3.6.1Connections multiplexed at the OBEX Command level...........................................373.6.2Connections multiplexed at the OBEX Transport layer............................................38
`4. OBEX APPLICATION FRAMEWORK .................................................................................. 39
`
`1.4.1Mapping OBEX packets to TinyTP/IrLMP packets...................................................12
`3.2.1Response Code values............................................................................................22
`

`

`4.1
`4.2
`4.3
`4.4
`4.5
`4.6
`
`4.6.1Directed Connection Mechanics..............................................................................414.6.2Target Header Processing.......................................................................................41
`4.7
`OBEX Access Methods ................................................................................................ 42
`
`4.7.1File Access..............................................................................................................424.7.2Database Access.....................................................................................................424.7.3Process / RPC.........................................................................................................42
`5. USING OBEX OVER IRDA ULTRA-LITE (CONNECTIONLESS USE) ................................. 43
`
`6.
`
`IRDA OBEX IAS ENTRIES, SERVICE HINT BIT AND TCP PORT NUMBER ...................... 44
`
`6.1
`
`6.2
`6.3
`
`IAS entry ....................................................................................................................... 44
`
`Service Hint bits ........................................................................................................... 44
`TCP port number.......................................................................................................... 44
`
`7. OBEX EXAMPLES ............................................................................................................... 45
`
`7.1
`7.2
`7.3
`7.4
`7.5
`
`Simple Put - file/note/ecard transfer ........................................................................... 45
`Simple Get - field data collection ................................................................................ 46
`Example Get of the Capability Object ......................................................................... 47
`Connect using Target, Who and Connection Id headers........................................... 48
`Combined Get and Put - paying for the groceries ..................................................... 49
`
`8. OBEX SERVICES AND PROCEDURES............................................................................... 51
`
`8.1
`
`Folder Browsing Service ............................................................................................. 51
`
`8.1.1Exchanging Folder Listings......................................................................................518.1.2Navigating Folders..................................................................................................528.1.3Security...................................................................................................................52
`8.2
`Simple OBEX Put file transfer (+ SetPath).................................................................. 53
`8.3
`Telecom/IrMC Synchronization Service...................................................................... 53
`8.4
`OBEX Get Default Object............................................................................................. 53
`
`8.5
`
`Capability Service ........................................................................................................ 54
`
`8.5.1The Capability Object/Database..............................................................................558.5.2The Object Profile Database...................................................................................558.5.3Locating the Capability Service...............................................................................55
`9. OBEX OBJECTS.................................................................................................................. 58
`
`9.1
`
`The Folder Listing Object............................................................................................ 58
`
`9.1.1Element Specification..............................................................................................589.1.2Folder Listing Details...............................................................................................619.1.3Encoding Folder Listing Objects..............................................................................629.1.4XML Document Definition........................................................................................63
`
`Generic File Object ...................................................................................................... 64
`
`9.2
`
`The Default OBEX Server............................................................................................. 39
`The Inbox Service ........................................................................................................ 39
`Inbox Connection......................................................................................................... 40
`Capability Service ........................................................................................................ 40
`Custom OBEX applications ......................................................................................... 40
`Directed Operations and Connections ....................................................................... 41
`
`Object Exchange ProtocolVersion 1.27
`
`9.2.1Introduction.............................................................................................................649.2.2Commonly Used Headers........................................................................................649.2.3Response Codes Commonly Used in File Exchange...............................................649.2.4Example Put Exchange...........................................................................................65
`
`The Capability Object .................................................................................................. 65
`
`9.3
`
`6.1.1IrDA:TinyTP:LsapSel...............................................................................................44
`8.4.1Get default vCard example.....................................................................................54
`

`

`9.4
`
`The Object Profile Object ............................................................................................ 68
`
`9.4.1Creating an Object Profile.......................................................................................689.4.2Object Profiles.........................................................................................................699.4.3Object Profile Example...........................................................................................69
`10.
`TEST GUIDELINES .......................................................................................................... 71
`
`10.1
`
`Introduction.................................................................................................................. 71
`
`10.1.1Objective.................................................................................................................7110.1.2Scope......................................................................................................................71
`10.2
`The Compliance Statement ......................................................................................... 71
`
`10.2.1Test Results............................................................................................................7110.2.2Required Behaviors.................................................................................................7210.2.3Client Questions......................................................................................................7210.2.4Server Questions....................................................................................................7310.2.5Test Numbering System..........................................................................................73
`
`Test Environment......................................................................................................... 74
`
`10.3
`
`10.3.1Physical Setup........................................................................................................7410.3.2Electromagnetic Interference Sources.....................................................................7410.3.3Test Personnel........................................................................................................74
`10.4
`Connected Tests .......................................................................................................... 74
`
`10.4.1Connect Operation..................................................................................................7410.4.2Disconnect Operation..............................................................................................7510.4.3Put Operation..........................................................................................................7510.4.4Get Operation.........................................................................................................7510.4.5Abort Operation.......................................................................................................7610.4.6SetPath Operation...................................................................................................7710.4.7Server Rejection Responses...................................................................................7710.4.8Miscellaneous Tests................................................................................................77
`
`Object Exchange ProtocolVersion 1.289.3.1General Information Section....................................................................................66
`
`10.5
`
`Non-Connected Tests .................................................................................................. 77
`
`10.5.1Ultra Put Tests........................................................................................................7710.5.2IAS Tests................................................................................................................7810.5.3Tiny TP Connection Tests.......................................................................................78
`10.6
`Header Tests ................................................................................................................ 79
`
`10.6.1Split Header Tests...................................................................................................7910.6.2Header Type Tests..................................................................................................79
`11.
`APPENDICES ................................................................................................................... 80
`
`11.1
`11.2
`11.3
`11.4
`11.5
`
`Minimum level of service ............................................................................................. 80
`Extending OBEX .......................................................................................................... 80
`Proposed Additions to OBEX...................................................................................... 80
`Known Target Identifiers ............................................................................................. 80
`MD5 Algorithm for Authentication .............................................................................. 80
`
`

`

`1.
`
`Introduction
`
`1.1 Tasks, Platforms, and Goals
`
`Object Exchange ProtocolVersion 1.29
`One of the most basic and desirable uses of the IrDA infrared communication protocols is simply to sendan arbitrary “thing”, or data object, from one device to another, and to make it easy for both applicationdevelopers and users to do so. We refer to this as object exchange (un-capitalized), and it is the subjectof the protocol described in this document.This document describes the current status of the protocol IrOBEX (for IrDA Object Exchange, OBEX forshort). OBEX is a compact, efficient, binary protocol that enables a wide range of devices to exchangedata in a simple and spontaneous manner. OBEX is being defined by members of the Infrared DataAssociation to interconnect the full range of devices that support IrDA protocols. It is not, however,limited to use in an IrDA environment.OBEX performs a function similar to HTTP, a major protocol underlying the World Wide Web. However,OBEX works for the many very useful devices that cannot afford the substantial resources required foran HTTP server, and it also targets devices with different usage models from the Web. OBEX is enoughlike HTTP to serve as a compact final hop to a device “not quite” on the Web.A major use of OBEX is a “Push” or “Pull” application, allowing rapid and ubiquitous communicationsamong portable devices or in dynamic environments. For instance, a laptop user pushes a file to anotherlaptop or PDA; an industrial computer pulls status and diagnostic information from a piece of factory floormachinery; a digital camera pushes its pictures into a film development kiosk, or if lost can be queried(pulled) for the electronic business card of its owner. However, OBEX is not limited to quick connect-transfer-disconnect scenarios - it also allows sessions in which transfers take place over a period of time,maintaining the connection even when it is idle.PCs, pagers, PDAs, phones, printers, cameras, auto-tellers, information kiosks, calculators, datacollection devices, watches, home electronics, industrial machinery, medical instruments, automobiles,and office equipment are all candidates for using OBEX. To support this wide variety of platforms, OBEXis designed to transfer flexibly defined “objects”; for example, files, diagnostic information, electronicbusiness cards, bank account balances, electrocardiogram strips, or itemized receipts at the grocerystore. “Object” has no lofty technical meaning here; it is intended to convey flexibility in what informationcan be transferred. OBEX can also be used for Command and Control functions - directives to TVs,VCRs, overhead projectors, computers, and machinery. Finally, OBEX can be used to perform complextasks such as database transactions and synchronization.OBEX is designed to fulfill the following major goals:1. Application friendly - provide the key tools for rapid development of applications.2. Compact - minimum strain on resources of small devices.3. Cross platform.4. Flexible data handling, including data typing and support for standardized types - this will allowdevices to be simpler to use via more intelligent handling of data inside.5. Maps easily into Internet data transfer protocols.6. Extensible - provide growth path to future needs like security, compression, and other extendedfeatures without burdening more constrained implementations.7. Testable and Debuggable.
`
`

`

`1.2 OBEX components
`
`The OBEX specification consists of two major parts: a protocol and an application framework. The OBEXprotocol is a session level protocol that specifies the structure for the conversation between devices. Italso contains a model for representing objects. The OBEX application framework is built on top of theOBEX protocol. Its main purpose is to facilitate interoperability between devices using the OBEXprotocol. Both of these are discussed in more detail below.
`
`1.2.1 OBEX Session Protocol
`
`• An object model that carries information
`
`about
`
`The OBEX protocol consists of two major elements: a model for representing objects (and informationthat describes the objects), and a session protocol to provide a structure for the “conversation” betweendevices. OBEX is a protocol for sending or exchanging objects and control information. In its simplestform, it is quite compact and requires a small amount of code to implement. It can reside on top of anyreliable transport, such as that provided by IrDA Tiny TP [IRDATTP] (including IrDA Liteimplementations), or TCP/IP stream sockets. OBEX consists of the following pieces:
` the objects being sent, as well as containing theobjects themselves. The object model is built entirely with parsable headers, similar in concept to theheaders in HTTP. • A session protocol, which structures the dialogue between two devices. The session protocol uses abinary packet-based client/server request-response model. • An IAS definition and hint bits for the service.
`
`Object Exchange ProtocolVersion 1.210
`
`

`

`packet. Once a connection is established all operations sent over theconnection are interpreted in a continuous context.Directed ConnectionA directed connection is one where the OBEX
` packet containstargeting information which the OBEX protocol uses to connect the client toits intended service or application.The Inbox ConnectionThe inbox connection is the OBEX connection made to the default OBEXserver, where the OBEX
`
`CONNECT
`
`CONNECT
`
`1.2.2 OBEX Application Framework
`
`The OBEX application framework is necessary to ensure interoperability between devices using OBEX. Itputs a structure on top of the OBEX protocol. The application framework is the foundation for a set ofstandard OBEX services that satisfy many object exchange requirements. OBEX implementations arenot required to follow the conventions specified by the application framework but doing so will ensureinteroperability with other devices. The table below outlines the elements of the OBEX applicationframework.
`
`Element
`
`Description
`
`CONNECT
`
`Object Exchange ProtocolVersion 1.211
`
`OBEX ClientAn OBEX Client is the entity that initiates the underlying transportconnection to an OBEX server and initiates OBEX operations.OBEX ServerAn OBEX Server is the entity that responds to OBEX operations. The OBEXserver waits for the OBEX client to initiate the underlying transportconnection.Default OBEX ServerThe Default OBEX server is the server that resides at the LSAP-Selspecified in the OBEX IAS definition. Other OBEX servers can exist but theDefault OBEX server is the “well known” server. This is analogous to theHTTP server located at TCP port number 80.OBEX ConnectionAn OBEX Connection is a virtual binding between two applications orservices. An OBEX connection is initiated by sending an OBEX
` packet does not contain targetingi