RM000504-0404 PS0130 PS0192 PS0153 UM0077 RM0006 UM0075 RM0007 INT32 INT16 - Datasheet Archive

 

ZirDATM 1.0 IrOBEX API Reference Manual RM000504-0404 ZiLOG Worldwide Headquarters · 532 Race Street · San Jose, CA

 

eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual RM000504-0404 RM000504-0404 ZiLOG Worldwide Headquarters · 532 Race Street · San Jose, CA 95126 Telephone: 408.558.8500 · Fax: 408.558.8300 · www.ZiLOG.com This publication is subject to replacement by a later edition. To determine whether a later edition exists, or to request copies of publications, contact: ZiLOG Worldwide Headquarters 532 Race Street, San Jose, CA 95126-3432 Telephone: 408.558.8500 Fax: 408.558.8300 www.ZiLOG.com Document Disclaimer ZiLOG is a registered trademark of ZiLOG Inc. in the United States and in other countries. All other products and/or service names mentioned herein may be trademarks of the companies with which they are associated. ©2004 by ZiLOG, Inc. All rights reserved. Information in this publication concerning the devices, applications, or technology described is intended to suggest possible uses and may be superseded. ZiLOG, INC. DOES NOT ASSUME LIABILITY FOR OR PROVIDE A REPRESENTATION OF ACCURACY OF THE INFORMATION, DEVICES, OR TECHNOLOGY DESCRIBED IN THIS DOCUMENT. ZiLOG ALSO DOES NOT ASSUME LIABILITY FOR INTELLECTUAL PROPERTY INFRINGEMENT RELATED IN ANY MANNER TO USE OF INFORMATION, DEVICES, OR TECHNOLOGY DESCRIBED HEREIN OR OTHERWISE. Devices sold by ZiLOG, Inc. are covered by warranty and limitation of liability provisions appearing in the ZiLOG, Inc. Terms and Conditions of Sale. ZiLOG, Inc. makes no warranty of merchantability or fitness for any purpose Except with the express written approval of ZiLOG, use of information, devices, or technology as critical components of life support systems is not authorized. No licenses are conveyed, implicitly or otherwise, by this document under any intellectual property rights. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual iii Table of Contents List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 About This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Abbreviations and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Manual Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Safeguards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 ZirDATM IrOBEX Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 IrOBEX Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 ZirDATM IrOBEX Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 IrOBEX Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 InBOX Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10 IrOBEX States . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11 ZirDATM IrOBEX API Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 ZirDATM Common APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 InBOX Server APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15 IrOBEX Server Application APIs . . . . . . . . . . . . . . . . . . . . . . . . . .15 IrOBEX Server Application Callback APIs . . . . . . . . . . . . . . . . . . .16 InBOX Client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16 IrOBEX Client Application APIs . . . . . . . . . . . . . . . . . . . . . . . . . . .16 IrOBEX Client Application Callback APIs . . . . . . . . . . . . . . . . . . .17 Use Cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19 IrOBEX InBOX Server Activation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20 RM000504-0404 RM000504-0404 Table of Contents eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual iv IrOBEX InBOX Server Deactivation . . . . . . . . . . . . . . . . . . . . . . . . . . 21 IrOBEX InBOX Put Operation-Success . . . . . . . . . . . . . . . . . . . . . . . 22 IrOBEX InBOX Put Operation-Failure . . . . . . . . . . . . . . . . . . . . . . . 23 IrOBEX InBOX Get Operation-Success . . . . . . . . . . . . . . . . . . . . . . 24 IrOBEX InBOX Get Operation-Failure . . . . . . . . . . . . . . . . . . . . . . . 25 IrOBEX InBOX Abort Operation-Success . . . . . . . . . . . . . . . . . . . . . 26 IrOBEX InBOX Abort Operation-Failure . . . . . . . . . . . . . . . . . . . . . 27 ZirDATM IrOBEX API Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Standard Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 API Definition Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 ZirDATM Common APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 InBOX Server APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 InBOX Server Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 InBOX Client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 OBEX Client Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Appendix A-Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Data Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Appendix B-Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 Appendix C-The ZiLOG Website . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Preprinted Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Customer Feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Table of Contents RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual v List of Figures Figure 1. Figure 2. Figure 3. Figure 4. Figure 5. Figure 6. Figure 7. Figure 8. Figure 9. Figure 10. RM000504-0404 RM000504-0404 Detailed Architecture of ZirDATM IrOBEX Layer . . . . . . . .9 IrOBEX States and Interactions . . . . . . . . . . . . . . . . . . . . .13 IrDA InBOX Server Activation . . . . . . . . . . . . . . . . . . . . .20 IrOBEX InBOX Server Deactivation . . . . . . . . . . . . . . . . .21 IrOBEX InBOX Put Operation-Success . . . . . . . . . . . . .22 IrOBEX InBOX Put Operation-Failure . . . . . . . . . . . . . .23 IrOBEX InBOX Get Operation-Success . . . . . . . . . . . . .24 IrOBEX InBOX Get Operation-Failure . . . . . . . . . . . . . .25 IrOBEX InBOX Abort Operation-Success . . . . . . . . . . .26 IrOBEX InBOX Abort Operation-Failure . . . . . . . . . . . .27 List of Figures eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual vi List of Figures RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual vii List of Tables Table 1. Table 2. Table 3. Table 4. Table 5. Table 6. Table 7. Table 8. Table 9. Table 10. Table 11. RM000504-0404 RM000504-0404 List of eZ80® and RZK Documentations . . . . . . . . . . . . . . .3 List of IrDA/IrOBEX-Related References . . . . . . . . . . . . . .3 List of Abbreviations and Acronyms . . . . . . . . . . . . . . . . . .4 Definition of IrDA/IrOBEX Terms . . . . . . . . . . . . . . . . . . . .4 Standard Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29 ZirDATM Common APIs . . . . . . . . . . . . . . . . . . . . . . . . . . .31 InBOX Server APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 InBOX Server Callback Functions . . . . . . . . . . . . . . . . . . .53 InBOX Client APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73 OBEX Client Callback Functions . . . . . . . . . . . . . . . . . . . .92 IrOBEX Data Type Definitions . . . . . . . . . . . . . . . . . . . .111 List of Tables eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual viii List of Tables RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 1 Introduction This reference manual describes the IrOBEX application layer of ZiLOG's IrDA implementation-the ZirDATM stack-and contains detailed descriptions of the APIs associated with the IrOBEX layer. The the ZirDATM stack can be used for ZiLOG's eZ80Acclaim!TM product line. The eZ80Acclaim!TM products referenced in this manual are the eZ80L92 microprocessor, and the eZ80F91 and eZ80F92 microcontrollers. About This Manual ZiLOG recommends that the user read and understand everything in this manual before using the product. We have designed this manual to be used as a reference guide for IrOBEX Applications Programming Interfaces (APIs). Intended Audience This document is a reference manual to aid application developers and product development engineers toward understanding the ZirDATM IrOBEX implementation and its APIs, and to design and build specific applications using these services. It is assumed that users are familiar with real-time operating systems and are experienced at working with microprocessors or in writing assembly code or compilers. Manual Organization The ZirDATM 1.0 IrOBEX API Reference Manual is divided into four chapters and two appendices. A brief description of each chapter is provided on the next page. RM000504-0404 RM000504-0404 Introduction eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 2 Introduction Presents an introduction to the ZirDATM 1.0 IrOBEX API Reference Manual in terms of its intended audience, manual organization, references, and conventions. ZirDATM IrOBEX Overview Presents an overview of the OBEX implementation of the ZirDATM SDK on the eZ80L92, eZ80F91, and eZ80F92 devices. ZirDATM IrOBEX API Summary Presents an overview of ZirDATM and IrOBEX APIs. Use Cases Contains several cases of how IrOBEX is used, in the form of flow diagrams. ZirDATM IrOBEX API Descriptions Contains a detailed description of the IrOBEX InBOX Server and Client APIs that are offered for building your application. Appendix A-Data Structures Lists the IrOBEX data structures. Appendix B-Error Conditions Lists the IrOBEX error codes. Related Documents ZiLOG recommends that the user be thoroughly familiar with the following documentation for the devices and the real-time ZiLOG kernel (RZK) upon which the ZirDATM stack is currently available. Table 1 lists the eZ80® and RZK documentations. Introduction RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 3 Table 1. List of eZ80® and RZK Documentations eZ80L92 Product Specification PS0130 PS0130 eZ80F91 Flash MCU with Ethernet MAC Product Specification PS0192 PS0192 eZ80F92/eZ80F93 Flash MCU Product Specification PS0153 PS0153 ® eZ80 CPU User Manual UM0077 UM0077 RZK Reference Manual* RM0006 RM0006 RZK User Manual* UM0075 UM0075 Note: *Assuming you have installed ZirDATM 1.0, this document is located in the following filepath on your PC: \rzk1.0.0\Docs. The documents listed in Table 2 are IrDA-specific reference documents. Table 2. List of IrDA/IrOBEX-Related References Topics References IrOBEX IrDA Object Exchange Protocol IrOBEX Infrared Data Association Version 1.2, March 18, 1999. IrMC Infrared Data Association Specifications for IrMobile (IrMC) Communications Version 1.1, March 1, 1999. TTP Infrared Data Association, Tiny Transport Protocol, TinyTP Version1.1, October 20, 1996. IrLMP Infrared Data Association, Link Management Protocol, IrLMP Version1.1, January 23, 1996. RM000504-0404 RM000504-0404 Introduction eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 4 Abbreviations and Acronyms Table 3 lists the abbreviations and acronyms associated with IrDA/ IrOBEX APIs. Table 3. List of Abbreviations and Acronyms Abbreviations Expansions API Application Programming Interface IrDA Infrared Data Association IrMC Infrared Mobile Communications OBEX OBject EXchange HTTP HyperText Transfer Protocol Definitions Table 4 lists the definition of terms associated with IrDA/IrOBEX. Table 4. Definition of IrDA/IrOBEX Terms Terms Definitions Capability Object The Capability Object finds information about the OBEX Server including device information, types of objects supported, object profiles and supported applications. InBOX InBOX is the default storage location for any OBEX server application. Object In OBEX the Object term is used to indicate the format used to transfer the data. OBEX Client OBEX Client is the entity that is used to send requests. OBEX Server OBEX Server is the entity used to service the Client requests and return the responses. Introduction RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 5 Manual Conventions The following assumptions and conventions are adopted to provide clarity and ease of use: Courier Typeface Code lines and fragments, functions, and various executable items are distinguished from general text by appearing in the Courier typeface. This convention is not used within tables. Safeguards When you use ZirDATM SDK along with ZiLOG's eZ80® Development Platform, follow the precautions listed below to avoid permanent damage to the platform. Note: Always use a grounding strap to prevent damage resulting from electrostatic discharge (ESD). 1. Power-up precautions a. Apply power to the PC and ensure that it is running properly. b. Start the terminal emulator program on the PC. c. Apply power through connector P3 on the development platform. 2. Power-down precautions When powering down, follow the sequence below: a. Quit the monitor program. b. Remove power from the development platform. Trademarks eZ80® is a registered trademark of ZiLOG, Inc. eZ80Acclaim!TM is a trademark of ZiLOG, Inc. RM000504-0404 RM000504-0404 Introduction eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 6 Introduction RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 7 ZirDATM IrOBEX Overview This chapter contains a basic discussion about IrOBEX, the architecture of ZirDATM IrOBEX implementation for the ZirDATM stack, and IrOBEX services that are currently available. IrOBEX Basics This reference manual describes object exchange (OBEX) functionality for protocols conforming to the Infrared Data Association (IrDA) standard. In this manual, this functionality is termed IrOBEX. IrOBEX provides a simplified communication protocol and application framework for easy transfer of arbitrary data that are encapsulated as Objects, such as files or other self-contained entities. Some objects are readily identifiable in OBEX and by the standard/popular applications that make use of OBEX services. For instance, OBEX recognizes object transfers to and from an InBOX. These objects can be: · A Targeted Object to a particular application (identified by transfer attributes) · · A File Object A Capability Object The Mobile Communications Application/Profile, or IrMC, recognizes Targeted Objects such as vCARD, vCALENDAR, and vMESSAGE. File Objects are recognized by the Folder Browsing Application that provides access to the remote folder using ZirDATM stack. Both IrMC and Folder Browsing Application services are defined as part of the ZirDATM specification. RM000504-0404 RM000504-0404 ZirDATM IrOBEX Overview eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 8 Capability Objects are OBEX and application-interpretable data that describe the capabilities of the peer OBEX implementation and those of the applications available above OBEX-this readily-accessible information facilitates maximum interworking between two independent implementations. For example, a sophisticated product with advanced features could restrict itself temporarily to work with a feature-limited peer and still provide a minimum level of service. User applications and prebuilt/OBEX-integrated applications that reside in separate IrDA-enabled devices can use OBEX services to provide a higher-level function such as personal calendar information synchronization, phone book synchronization, exchange of business cards, browse folders, transfer files, and more. The scope and availability of these services are defined by the nature of the product being designed, such as a PDA, cell phone, pager, or respective user profiles. The name and type descriptors that are part of the transferred content typically describe OBEX objects. In the case of a targeted object delivery, the delivered object can be readily discernible by the recipient. OBEX's object description and delivery mechanisms are parallel to the popular HTTP1.1 transfer protocol and support MIME-type objects. ZirDATM IrOBEX Architecture As illustrated in Figure 1, ZiLOG's OBEX implementation provides two types of services: 1. A higher level of OBEX service abstraction called the OBEX Services API (represented by the oval in Figure 1). This service also shields the application from all OBEX-specific data formats and representations. 2. An interior or lower level of services called OBEX Session Protocol used to make the format for the actual conversation between any two ZirDATM IrOBEX Architecture RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 9 devices, that is, this service uses the object model of IrOBEX to format the packets and send them to the other end. Application Application IrOBEX Client IrOBEX Server IrOBEX Services API IrOBEX Services API IrOBEX session Protocol IrOBEX session Protocol IrDA - Stack IrDA - Stack Responses from the server IR - medium Requests from the client Application (like Laptop making File Transfer) IrOBEX session protocol which provides the structure for the conversation between the two devices Core layers of the IrDA stack (IrLMP, IrLAP, Framer and Physical Layer) These are the IrOBEX Services Client/ Server APIs provided to the user by the IrOBEX layer. This is the only way of communication between the application and IrOBEX. Figure 1. Detailed Architecture of ZirDATM IrOBEX Layer RM000504-0404 RM000504-0404 ZirDATM IrOBEX Architecture eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 10 IrOBEX Services The following IrOBEX services are available to applications: · · InBOX services OBEX Register and ZirDA Stack Enabling The following section describes all actions and services that can be performed using the ZirDATM OBEX default connection. This service incorporates both OBEX Server and Client operating modes; that is, an application can be either a server that provides information or services to the remote end, or a client that requests information or services from the remote end. ZirDATM IrOBEX provides all these services. For more details on IrDA IrOBEX protocol layer, refer to Table 2 on page 3. InBOX Services The InBOX service encapsulates a number of operating modes. The primary modes are the InBOX Server mode and the InBOX Client mode. InBOX Server Operation The InBOX Server represents the default services provided by a local device to other IrDA devices. Service requests by a remote client application are routed to the application entity that is registered as the InBOX Server. There must only be one default InBOX Server application associated with the IrOBEX at any given time. IrOBEX defines the following default InBOX Server/Connection services: · · IrOBEX Services A simple OBEXPut service for a file or object transfer by a remote device; requires an InBOX Server application. An OBEXGetObject service by a remote device; requires an InBOX Server application. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 11 · An OBEXAbort service by a remote device, requires an InBOX Server application. InBOX Client Operation InBOX Client operations are performed by OBEX when an associated application requests a service from the remote end. Service requests by the Client application are routed to the InBOX Server entity at the remote end. Any Client application can use InBOX Client Services; however, only one Client application can use InBOX services at a time. This statement is also true for the operating mode. If a connection exists at the OBEX layer to perform in the Server operating mode, no Client application is allowed to access the InBOX Client operation. If a connection has already been set up because of a previous Client operation request, Server operating mode is not possible (on the same device), nor are additional Client applications permitted to use OBEX services until the requests by the first application are complete and the connection closed. Note: Because of the directional nature of ZirDATM stack, OBEX does not support simultaneous operations to multiple devices. The OBEX implementation can only support a single connection to a single device at any given time. OBEX defines the following default InBOX Client services: · A simple OBEXPut service for a file or an object transfer to a remote device; initiated by an InBOX Client application · An OBEXGetObject service from a remote device; initiated by an InBOX Client application · An OBEXAbort service to abort a file transfer that is in progress initiated by the InBOX Client application. IrOBEX States Initially, an OBEX implementation can exist in one of three states. These three states are: RM000504-0404 RM000504-0404 IrOBEX Services eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 12 · · · Unregistered/IrDA Disabled Registered/IrDA Disabled Registered/IrDA Enabled On power-up, IrOBEX starts in the Unregistered/IrDA Disabled state-which is essentially a dormant state-and waits for an InBOX server application to register itself with OBEX. When a valid server application registers itself, OBEX shifts to the Registered/IrDA Disabled state-still dormant-until the ZirDATM stack is initiated. IrOBEX is then activated. Note: The Unregistered/IrDA Disabled and Registered/IrDA Disabled states are provided for the purposes of ZirDA power conservation and ZirDATM security. An active ZirDATM connection with a registered InBOX server application represents the Registered/Enabled state. The OBEX implementation can remain idle while waiting for a service request representing the Server mode of operation (by default), or it can initiate a service request, in which case it operates in Client mode. See Figure 2. IrOBEX Services RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 13 In this initial state all APIs are ignored, except ObexRegisterInBOXServer Power-ON Unregistered and IrDA Disabled When an InBOX Server Application is registered OBEX Services can be enabled / disabled. ObexRegisterInBOXServer() In the disabled state, no IrDA activity occurs. Therefore, none of the API calls are accepted, except IrDAActivate. Registered and IrDA Disabled IrDAActivate() IrDADeactivate() In the enabled state, the IrDA stack is initialized and it actively listens for incoming connections. The stack accepts all OBEX API calls, by default. OBEX Connection Request Received Registered and IrDA Enabled OBEX Connection Initiated OBEX Connection Closed Server Mode In Server Mode, all Client API calls rejected OBEX Connection Closed Client Mode In Client Mode, all Server API calls rejected Figure 2. IrOBEX States and Interactions RM000504-0404 RM000504-0404 IrOBEX Services eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 14 IrOBEX Services RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 15 ZirDATM IrOBEX API Summary IrOBEX services are categorized by their nature and by operating modes. The following sections introduce IrOBEX service APIs. ZirDATM Common APIs The ZirDATM IrOBEX layer requires two Common APIs to activate and to deactivate the IrDA stack. These APIs are described in the ZirDATM 1.0 Common API Reference Manual (RM0007 RM0007) located in the path: \ZirDA1.0\docs. The Common APIs are: · · IrDAActivate() IrDADeactivate() InBOX Server APIs InBOX Server APIs are of two types: the InBOX Server application APIs and the InBOX Server application Callback APIs. These APIs report various asynchronous incoming InBOX connection events and operations to the server application. IrOBEX Server Application APIs The list below represents common IrOBEX Server application APIs. ObexRegisterInBoxServer() ObexGetServerResponse() ObexKillLink() ObexPutServerResponse()* ObexDisconnectServerResponse()* ObexAbortServerResponse()* ObexConnectServerResponse()* Note: *Optional APIs. RM000504-0404 RM000504-0404 ZirDATM IrOBEX API Summary eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 16 IrOBEX Server Application Callback APIs The Callback APIs listed below are provided during server registration. ObexConnectServerInd() ObexPutServerInd() ObexGetServerInd() ObexAbortServerInd() ObexDisconnectServerInd() InBOX Client APIs There are InBOX Client application Callback APIs for each of the InBOX Client application APIs. These Callback APIs report the success or failure status of a client request to OBEX. ObexDiscoverDevices() ObexStartClientTransaction() ObexInboxPut() ObexInboxGet() ObexAbort() ObexEndClientTransaction() IrOBEX Client Application APIs The list below represents common IrOBEX Client application APIs. ObexDiscoverDevices() ObexStartClientTransaction() ObexAbort() ObexInboxPut() InBOX Client APIs ObexInboxGet() ObexEndClientTransaction() RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 17 IrOBEX Client Application Callback APIs These Callback APIs are provided as an argument in each of the IrOBEX Client application APIs. ObexDiscoverClientCfm() ObexStartClientCfm() ObexPutClientCfm() ObexGetClientCfm() ObexAbortClientCfm() ObexEndClientCfm() RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 18 InBOX Client APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 19 Use Cases The following sections describe use cases to illustrate how the ZirDATM IrOBEX APIs can be used to perform various IrOBEX related services. Any application that requires IrOBEX APIs must follow the predefined sequence of API calls as illustrated in the use case diagrams. When the system gets booted up, any application must first register itself with IrOBEX by calling ObexRegisterInboxServer() API. By default, any application acts as a server first. When once it registers successfully, the stack must be activated by calling IrDACTivate() API. Now the application can act as a client or can remain as a server for incoming connections. To act as a client, the user application must make the following API calls, which are in sequence: APIs Description ObexStartClientTransaction() Used to make a connection with the server ObexInboxPut() Used to make a file transfer ObexAbort() Used to abort the file transfer that is in progress ObexEndClientTransaction() Used to close the existing connection When the existing connection is closed using ObexEndClientTransaction() API, the application can either act as a client or a server. RM000504-0404 RM000504-0404 Use Cases eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 20 IrOBEX InBOX Server Activation Figure 3 illustrates the API call flow for InBOX Server activation. OBEX Inbox Local InBOX Server Application Remote IrDA Device SUCCESSFUL OPERATION (Unregistered IrDA disabled mode) ObexRegisterInBOXServer NORMAL OPERATION (Registered, IrDA disabled mode) IrDAActivate() Function returns SUCCESS OBEX starts to Enables local IrDA stack operation Connect listen for incoming Data transfer FAILED OPERATION (Server/Client mode) IrDAActivate() Function returns ERROR Link is already active Figure 3. IrDA InBOX Server Activation IrOBEX InBOX Server Activation RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 21 IrOBEX InBOX Server Deactivation Figure 4 illustrates the API call flow for InBOX Server deactivation. InBOX Server Application OBEX Inbox Local Remote IrDA Device SUCCESSFUL OPERATION (Registered IrDA enabled mode) IrDADeactivate() Function returns SUCCESS Disables local IrDA stack operation IrDA stack is not able to receive data from remote device FAILED OPERATION (Server/Client mode) IrDADeactivate() Function returns ERROR OBEX is busy processing requests from remote Client Link is still active Figure 4. IrOBEX InBOX Server Deactivation RM000504-0404 RM000504-0404 IrOBEX InBOX Server Deactivation eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 22 IrOBEX InBOX Put Operation-Success Figure 5 illustrates a successful API call flow for the InBOX Put operation. InBOX Client Application IrOBEX Client InBOX Server Application IrOBEX Server ObexStartClientTransaction Connect Connect Response ObexStartClientCfm (callback) ObexInBOXPut ObexConnectServerInd (callback) ObexConnectServerResponse (opt) Put Operation ObexPutServerInd (callback) ObexPutClientCfm (Continue rsp) ObexInBOXPut ObexPutClientCfm (success rsp) ObexEndClientTransaction ObexEndClientCfm (callback) Response with Continue Put Operation Success response Disconnect Operation Success response code ObexPutServerResponse (opt) ObexPutServerInd (callback) ObexPutServerResponse (opt) OBEXDiscServerInd (callback) OBEXDiscServerResponse (opt) Figure 5. IrOBEX InBOX Put Operation-Success IrOBEX InBOX Put Operation-Success RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 23 IrOBEX InBOX Put Operation-Failure Figure 6 illustrates a failed API call flow for the InBOX Put operation. InBOX Client Application IrOBEX Client InBOX Server Application IrOBEX Server ObexStartClientTransaction Connect Connect Response ObexStartClientCfm (callback) ObexInBOXPut ObexPutClientCfm (failure rsp) ObexEndClientTransaction ObexEndClientCfm (callback) Put Operation Failure response Disconnect Operation Success response code ObexConnectServerInd (callback) ObexConnectServerResponse (opt) ObexPutServerInd (callback) ObexPutServerResponse (opt) OBEXDiscServerInd (callback) OBEXDiscServerResponse (opt) Figure 6. IrOBEX InBOX Put Operation-Failure RM000504-0404 RM000504-0404 IrOBEX InBOX Put Operation-Failure eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 24 IrOBEX InBOX Get Operation-Success Figure 7 illustrates a successful API call flow for InBOX Get Operation. InBOX Client Application IrOBEX Client InBOX Server Application IrOBEX Server ObexStartClientTransaction Connect Connect Response ObexStartClientCfm (callback) ObexInBOXGet ObexGetClientCfm (More data to come) ObexInBOXGet ObexGetClientCfm (Success) ObexEndClientTransaction ObexEndClientCfm (callback) Get Operation Get Response (more data to come) Get Operation Get Response (Success) Disconnect Operation Success response code ObexConnectServerInd (callback) ObexConnectServerResponse (opt) ObexGetServerInd (callback) ObexGetServerResponse ObexGetServerInd (callback) ObexGetServerResponse OBEXDiscServerInd (callback) OBEXDiscServerResponse (opt) Figure 7. IrOBEX InBOX Get Operation-Success IrOBEX InBOX Get Operation-Success RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 25 IrOBEX InBOX Get Operation-Failure Figure 8 illustrates a failed API call flow for the InBOX Get operation. InBOX Client Application IrOBEX Client InBOX Server Application IrOBEX Server ObexStartClientTransaction Connect Connect Response ObexStartClientCfm (callback) ObexInBOXGet ObexGetClientCfm (Failure) ObexEndClientTransaction ObexEndClientCfm (callback) Get Operation Get Response (Failure) Disconnect Operation Success response code ObexConnectServerInd (callback) ObexConnectServerResponse (opt) ObexGetServerInd (callback) ObexGetServerResponse OBEXDiscServerInd (callback) OBEXDiscServerResponse (opt) Figure 8. IrOBEX InBOX Get Operation-Failure RM000504-0404 RM000504-0404 IrOBEX InBOX Get Operation-Failure eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 26 IrOBEX InBOX Abort Operation-Success Figure 9 illustrates the API call flow for an InBOX Abort operation. InBOX Client Application IrOBEX Client InBOX Server Application IrOBEX Server ObexStartClientTransaction Connect Connect Response ObexStartClientCfm (callback) ObexInBOXPut ObexConnectServerInd (callback) ObexConnectServerResponse (opt) Put Operation ObexPutServerInd (callback) ObexPutClientCfm (Continue rsp) ObexAbort ObexAbortClientCfm (success rsp) ObexEndClientTransaction ObexEndClientCfm (callback) Response with Continue Abort Operation Success response Disconnect Operation Success response code ObexPutServerResponse (opt) ObexAbortServerInd (callback) ObexAbortServerResponse (opt) OBEXDiscServerInd (callback) OBEXDiscServerResponse (opt) Figure 9. IrOBEX InBOX Abort Operation-Success IrOBEX InBOX Abort Operation-Success RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 27 IrOBEX InBOX Abort Operation-Failure Figure 10 illustrates the API call flow for the InBOX Abort operation. InBOX Client Application IrOBEX Client InBOX Server Application IrOBEX Server ObexStartClientTransaction Connect Connect Response ObexStartClientCfm (callback) ObexInBOXPut ObexConnectServerInd (callback) ObexConnectServerResponse (opt) Put Operation ObexPutServerInd (callback) ObexPutClientCfm (Continue rsp) ObexAbort ObexAbortClientCfm (failure rsp) ObexEndClientTransaction ObexEndClientCfm (callback) Response with Continue Abort Operation Failure response Disconnect Operation Success response code ObexPutServerResponse (opt) ObexAbortServerInd (callback) ObexAbortServerResponse (opt) OBEXDiscServerInd (callback) OBEXDiscServerResponse (opt) Figure 10. IrOBEX InBOX Abort Operation-Failure RM000504-0404 RM000504-0404 IrOBEX InBOX Abort Operation-Failure eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 28 IrOBEX InBOX Abort Operation-Failure RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 29 ZirDATM IrOBEX API Descriptions This section provides detailed descriptions of the IrOBEX APIs available with the ZirDATM 1.0 release. To use the ZirDATM IrOBEX APIs, the zobx_api.h file must be included in the application program. Standard Data Types IrOBEX uses the standard data types defined in the common_types.h file. Table 5 defines these data types. Table 5. Standard Data Types Data Type Definition INT32 INT32, INT16 INT16 Represents signed integer entity that is 32-bit and 24-bit. UINT32 UINT32, UINT16 UINT16 Represents unsigned integer entity that is 32-bit and 24-bit. INT8 Standard character. UINT8 Denotes unsigned character. VOID Equivalent to target compiler's void type API Definition Format Descriptions for each ZirDATM 1.0 API follow a standard format. In this document, header file names are shown at the top of the page, followed by the API description. A brief discussion of the format for each API description follows. RM000504-0404 RM000504-0404 ZirDATM IrOBEX API Descriptions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 30 Function Prototype The Function Prototype section contains the exact declaration of the API call. Description The Description section contains a paragraph describing the API. Arguments The Arguments section describes the arguments (if any) to the API. Return Value The Return Value section describes the return value of the API, if any. Example The Example section can contain one or more examples of how the API function is called. See Also The See Also section lists related API calls, with hyperlinks for each for quick reference. The ZirDATM SDK IrOBEX API descriptions begin on the next page. API Definition Format RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 31 ZirDATM Common APIs Table 6 lists the ZirDATM Common APIs. These APIs are described in the ZirDATM 1.0 Common API Reference Manual (RM0007 RM0007). Table 6. ZirDATM Common APIs IrDAActivate() IrDADeactivate() Assuming you have installed ZirDATM 1.0, the ZirDATM 1.0 Common API Reference Manual (RM0007 RM0007) document is located in the following filepath: \ZirDA1.0\docs\. RM000504-0404 RM000504-0404 ZirDATM IrOBEX API Descriptions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 32 InBOX Server APIs The InBOX Server APIs can be called only after a registered server application has activated IrOBEX. Table 7 lists the InBOX Server APIs. Use the links provided below to jump quickly to any of the APIs. Table 7. InBOX Server APIs ObexRegisterInBoxServer() ObexGetServerResponse() ObexPutServerResponse() ObexAbortServerResponse() ObexDisconnectServerResponse() ObexKillLink() The InBOX server API descriptions begin on the next page. InBOX Server APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 33 ObexRegisterInBoxServer() #include "zobx_api.h" OBEX_RET ObexRegisterInBoxServer( OBEX_SERVER_CALLBACK_FUNC *srvrCB); Description This API allows the user application to register all callbacks with the OBEX InBOX Server. Whenever the OBEX Server detects a request/ event from the peer it notifies the Application through these callbacks. Arguments srvrCB Pointer to the structure OBEX_SERVER_CALLBACK_FUNC containing the addresses of all the callback functions. Return Values OBEX_SUCCESS OBEX_FAILED_BELOW Indicates the failure at the lower layers. OBEX_INVALID_ARG Specifies that the passed parameter is invalid or incomplete already been registered with OBEX. OBEX_ALREADY_REGISTERED RM000504-0404 RM000504-0404 Indicates that the function returned successfully (always overwrites the callback functions received in an earlier call with those arguments received in the present API invocation. Indicates that the application has already registered the callbacks with OBEXServer. This API was called before. InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 34 Example OBEX_RET retValue; OBEX_CALLBACK_RET ObexSrvrConnInd (UINT8 reqId, OBEX_DEVICE_ID deviceId, UINT16 UINT16 clientMaxPktLen, UINT16 UINT16 *serverMaxPktLen, UINT32 UINT32 objCount, UINT32 UINT32 objLength, INT8 *desc, INT8 *friendlyName); OBEX_CALLBACK_RET ObexSrvrDiscInd( UINT8 reqId, OBEX_DISC_REASON discReason, INT8 *desc); OBEX_CALLBACK_RET ObexServerAbortInd(UINT8 reqId, INT8* desc); OBEX_CALLBACK_RET ObexServerPutInd(UINT8requestId, INT8* objectName, INT8* mimeType, INT8* putData, UINT32 UINT32 maxObjLen, UINT16 UINT16 curPktLen, INT8* description, PUT_STATUS_CODE status); OBEX_CALLBACK_RET ObexServerGetInd( UINT8 reqId,INT8 *objName, INT8 *objType, UINT16 UINT16 maxPktLen, INT8 *desc); OBEX_SERVER_CALLBACK_FUNC fPtrs = { d,ObexServerGetInd}; retValue = ObexRegisterInBoxServer(&fPtrs); if(retValue != OBEX_SUCCESS) { /* Process Abnormal situation here */ } else InBOX Server APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 35 { /* Successfully registered all the Server callbacks, comes to the registered/nonActive state */ /* Continue doing with ObexActivateIrDA() API call */} RM000504-0404 RM000504-0404 InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 36 ObexConnectServerResponse() #include "zobx_api.h" OBEX_RET ObexConnectServerResponse( UINT8 responseIdentifier, CONNECT_RESPONSE_CODE responseCode, UINT16 UINT16 maxPktLen, INT8 *description); Description This API allows the OBEX server to send a response to the Client's Connect request. This API can only be called one time, and immediately after the OBEXInBOXConnectServerInd() callback function is invoked. Arguments responseIdentifier Response ID must match the ID present in the ObexConnectServerInd(). responseCode Response Code sent by the Application. It can be one of the following: OBEX_SUCCESS: Indicates that the Server Application accepted the Connection. OBEX_FAILURE: Indicates that the connection is rejected. maxPktLen description InBOX Server APIs Length of the packet allowed in one response packet. Description about the Connect Response if any (Null terminated string). RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 37 Return Values OBEX_SUCCESS Indicates that the function returned successfully. OBEX_FAILURE Indicates the failure because of unknown or other reasons. OBEX_INVALID_ARG Indicates that the passed argument is invalid. OBEX_UNABLE_SEND_MSG Indicates that the request was not sent. OBEX_MEM_ALLOC_FAILURE Indicates that error occurred in allocating memory. OBEX_BUSY Indicates that the request cannot be processed temporarily. Example #define MAX_PACKET_LEN 2096 UINT16 UINT16 pketLen = MAX_PACKET_LEN; OBEX_RET connectReturnValue; CONNECT_RESPONSE_CODE responseCode = OBEX_SUCCESS; connectReturnValue = ObexConnectServerResponse( rspId, responseCode,pketLen,NULL); If(connectReturnValue != OBEX_SUCCESS) {/* Server should be waiting for the other incoming Connect requests */ } else { /* Connection is made successfully */ obex_next_state = OBEX_CONNECTED; } RM000504-0404 RM000504-0404 InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 38 See Also ObexConnectServerInd() COMMON_RSP_CODE ObexStartClientTransaction() InBOX Server APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 39 ObexGetServerResponse() #include "zobx_api.h" OBEX_RET ObexGetServerResponse( UINT8 responseIdentifier, UINT8 * data, UINT32 UINT32 maxObjLen, UINT16 UINT16 curPktLen, INT8 * description, GET_STATUS_CODE status ); Description This API allows the Server application to send the requested data to the OBEX Client. This API can only be called one time, and immediately after the ObexGetServerInd() callback function is invoked. Arguments responseIdentifier data Actual data to be sent. maxObjLen Length of the whole object. curPktLen Length of the data that is being transmitted. description RM000504-0404 RM000504-0404 Indicates a unique value for the request passed in by the OBEX Server while sending the Client's request through the ObexGetServerInd() callback, so that the Server application responds with the same value. The number is the same for the whole object transfer, which means that all the GET indications for the same object contain the same number. Optional description for both normal and Failure conditions. InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 40 status Indicates the status of the data transfer. Possible values are: OBEX_NOT_FOUND: Indicates that the requested object is not found at the Server. OBEX_MORE_DATA_TO Indicates that there is data _COME: still pending to be sent OBEX_NO_MORE_DATA: Indicates that this is the last packet being sent OBEX_UNSUPPORTED_ MEDIA_TYPE: Indicates that the media type is not supported by the Application OBEX_FORBIDDEN: Indicates that the request is not accepted, and is not serviced Return Values OBEX_SUCCESS OBEX_FAILURE Indicates the failure because of unknown or other reasons. OBEX_INVALID_ARG InBOX Server APIs Indicates that the function returned successfully. Indicates the passed argument is invalid. If the max_packet_len is passed with every ObexGetServerResponse() API, it must be same as the one present in the very first ObexGetServerResponse() API. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 41 OBEX_OVERSIZED_DATA The length of the current packet exceeds the maximum packet length negotiated (the maximum acceptable size having been passed to the application using the ObexGetServerInd() callback function in the very first ConnectIndication/GetIndication). OBEX_UNABLE_SEND_MSG Indicates that the message cannot be sent. OBEX_MEM_ALLOC_FAILURE Indicates that error occurred in allocating memory. OBEX_BUSY Indicates that the request cannot be processed temporarily. Comments The ObexGetServerResponse() API can be invoked by the Server application many times to transfer the requested object. However, this response API must be called only in response to each invocation of the ObexGetServerInd*-() callback function. A number of additional parameters do not require any real contents during a subsequent ObexGetServerResponse() invocation. For example, the Description header can make sense only for the first instance and could be NULL for subsequent operations. Similarly, maxobjLen is also provided as information to the peer and is not necessarily provided during subsequent GET responses. However, if a value is provided, it must be set to that value each time. Examples #define #define INT8 INT8 UINT16 UINT16 MAX_DESC_LEN 50 MAX_PACKET_LEN 2000 desc[MAX_DESC_LEN]; data[MAX_PACKET_LEN]; max_packet_len; RM000504-0404 RM000504-0404 InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 42 UINT16 UINT16 cur_packet_len; OBEX_RET retValue; UINT8 rspId = requestId;( requestId received through the GetServerIndication callback) Case 1: In this case, the Server is sending more data; this is the first packet being sent. GET_STATUS_CODE statusCode = OBEX_MORE_DATA_TO_COME; retValue = ObexGetServerResponse( rspId, &data, max_packet_len,cur_packet_len,&desc, statusCode); if(retValue != OBEX_SUCCESS) { /* it could be that the passed data has the errors listed above */ } else { /* Successful in sending the data to the peer, */ } Case 2: In this scenario, the Server application is sending data that can fit into only one packet. GET_STATUS_CODE statusCode = OBEX_NO_MORE_DATA; UINT8 responseId = requestId;(requestId received through the GetServerIndication callback) retValue = ObexGetServerResponse(responseId, &data, max_packet_len,cur_packet_len,&desc, statusCode); if(retValue != OBEX_SUCCESS) { InBOX Server APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 43 /* it could be that the passed data has the errors listed above */ } else { /* Successful in sending the data to the peer, this is the last to be sent. */ } Case 3: In this case, Server application is sending data in multiple packets, and this is the last packet to be sent. Parameters such as `max_packet_len' and `description' could be NULL. If max_packet_len is passed, it should be the same as the packet length sent in the first packet. GET_STATUS_CODE statusCode = OBEX_NO_MORE_DATA; retValue = ObexGetServerResponse(responseId, &data, max_packet_len,cur_packet_len,&desc, statusCode); if(retValue != OBEX_SUCCESS) { /* it could be that the passed data has the errors listed above */ } else { /* Successful in sending the data to the peer, this is the last to be sent. */ } See Also ObexInboxGet() GET_STATUS_CODE ObexGetServerInd() RM000504-0404 RM000504-0404 InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 44 ObexPutServerResponse() #include "zobx_api.h" OBEX_RET ObexPutServerResponse( UINT8 responseIdentifier, PUT_STATUS_CODE status, INT8 *description); Description This API allows the OBEX Server to send a response to the Client's PUT request. This API can only be called one time, and immediately after the ObexPutServerInd() callback function is invoked. Arguments responseIdentifier This value uniquely identifies the request and the corresponding response from the Server. This number must be the same as the requestIdentifier passed by the Server in the ObexPutServerInd(). status Indicates whether the data transfer must continue or not (that is, whether it is okay for the Client to send more data associated with the same Put request). Possible values are: OBEX_EXPECT_MORE_DATA Indicates that the : Server application is expecting more data from the Client application. OBEX_FORBIDDEN: InBOX Server APIs Indicates that the server Application has not accepted the request. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 45 status (continued) OBEX_SUCCESS: Indicates this is the successful end of data transfer. OBEX_CREATED: Indicates that the requested empty object has been created. OBEX_DELETED: Indicates that the requested object has been deleted. OBEX_ENTITY_TOO_LARGE: Indicates that the received entity is very large. OBEX_OBJ_TYPE_NOT_ SUPPORTED: description Indicates that the Server Application does not suport the mime type of the recieved object. Optional description for both normal and Failure conditions. Return Values OBEX_SUCCESS OBEX_FAILURE Indicates the failure due to unknown or other reasons. OBEX_INVALID_ARG Indicates the passed argument is invalid. OBEX_UNABLE_SEND_MSG Indicates that an error occurred while sending the message. OBEX_MEM_ALLOC_FAILURE RM000504-0404 RM000504-0404 Indicates that the function returned successfully. Indicates that an error occurred while allocating memory. InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 46 OBEX_BUSY Indicates that the request cannot be processed temporarily. Comments Because a PUT response can be generated from the Server application many times (when the Client is attempting to PUT a large object), the meaning and use of the Description header may only be necessary in the first instance. The contents of the Description header can be NULL during subsequent operations with respect to the same associated PUT object transaction. Example INT8 UINT8 OBEX_RET PUT_STATUS_CODE desc[MAX_DESC_LEN]; responseId; retValue; putStatusCode = OBEX_EXPECT_MORE_DATA; Case 1: In this case the Server application is expecting more data from the Client by giving a response code as OBEX_EXPECT_MORE_DATA. retValue = ObexPutServerResponse (responseId, putStatusCode, &desc); If(retValue != OBEX_SUCCESS) { /* Process Abnormal situation here */ } else { /* Able to send data to the OBEX Server, and expecting one more PUT request from the Peer to receive the remainder of the data */ } InBOX Server APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 47 Case 2: The object to be sent can either fit into only one packet or this is the last PUT response API call for the same object. PUT_STATUS_CODE putStatusCode = OBEX_SUCCESS; retValue = ObexPutServerResponse(responseId, &desc, putStatusCode); If(retValue != OBEX_SUCCESS) { /* OBEX Server just breaks the link */ } else { /* Successfully sent the packet */ } See Also ObexInboxPut() PUT_STATUS_CODE ObexPutServerInd() RM000504-0404 RM000504-0404 InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 48 ObexAbortServerResponse() #include "zobx_api.h" OBEX_RET ObexAbortServerResponse( UINT8 responseIdentifier, ABORT_STATUS_CODE rspCode, INT8 *description ); Description The ObexAbortServerResponse API allows the OBEX Server to send a response to the Client`s Abort request. This API can only be called one time, and immediately after the ObexAbortServerInd() callback function is invoked. Arguments Server Application responseIdentifier Must match requestId given in the ObexAbortServerInd() callback rspCode Response Code sent by the Application. It could be one of the following: OBEX_SUCCESS: Indicates that the Server application has accepted the Connection. OBEX_FAILURE: Indicates that the connection is rejected. description Optional Description for the abort request (Null terminated string). Return Values OBEX_SUCCESS InBOX Server APIs Indicates that the function returned successfully. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 49 OBEX_FAILURE Indicates the failure due to unknown or other reasons. OBEX_MEM_ALLOC_FAILURE Indicates that an error occurred while allocating memory. OBEX_UNABLE_SEND_MSG Indicates that an error occurred while sending the message. OBEX_INVALID_ARG Indicates that the passed arguments are invalid. OBEX_BUSY Indicates that the request cannot be processed temporarily. Example OBEX_RET abortRetValue; UINT8 responseId = requestId; /*Id received in the Abort Indication callback */ INT8 description[MAX_DESC_LEN]; abortRetValue = ObexAbortServerResponse(responseId, OBEX_SUCCESS, &description); if(abortRetValue = OBEX_BUSY ) { /* OBEX Server is busy in processing other requests */ } else if(abortRetValue = OBEX_SUCCESS) { /* If the Abort call comes from the Client Application in the middle of PUT operation, the Server Application can clean up the data that has been received so far */ } See Also ObexAbort() ObexAbortServerInd() RM000504-0404 RM000504-0404 InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 50 ObexDisconnectServerResponse() #include "zobx_api.h" OBEX_RET ObexDisconnectServerResponse( UINT8 responseIdentifier, INT8 *description); Description This API allows the OBEX Server to send a response to the Client`s Disconnect request. This API can only be called one time, and immediately after the ObexDisconnectServerInd() callback function is invoked. Arguments responseIdentifier Should match the requestIdentifier provided in the ObexDisconnectServerInd() callback. description Optional description about the disconnect response. Return Values OBEX_SUCCESS OBEX_MEM_ALLOC_FAILURE Indicates that an error occurred while allocating memory. OBEX_UNABLE_SEND_MSG Indicates that an error occurred while sending the message. OBEX_INVALID_ARG Indicates that the passed arguments are invalid. OBEX_BUSY InBOX Server APIs Indicates that the function returned successfully. Indicates that the request cannot be processed temporarily. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 51 Comments The specifications suggest that the Disconnect request may not be refused, so the response code always is Success if the connection exists. Example OBEX_RET retValue; INT8 description[MAX_DESC_LEN]; retValue = ); If( retValue = OBEX_INVALID_ARG ) { /* Passed argument is invalid */ } else if( retValue = OBEX_SUCCESS ) { /* Application can clean up the global data structures used for the connection if any */ } See Also ObexDisconnectServerInd() ObexEndClientTransaction() RM000504-0404 RM000504-0404 InBOX Server APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 52 ObexKillLink() #include "zobx_api.h" OBEX_RET ObexKillLink ( INT8 *description); Description The ObexKillLink API allows the Server application to forcibly break the link if the connection is alive. This API allows any Watchdog entity to forcibly clear a connection with a malfunctioning remote device, or where, for instance, the Server connection could be cleared to facilitate Client operations. Arguments description Reason to break the link. Return Values OBEX_SUCCESS Indicates that the function returned successfully. OBEX_NO_CONNECTION Indicates that the OBEX connection no longer successfully exists. Example OBEX_RET retValue; INT8 description[MAX_DESC_LEN]; retValue = ObexKillLink(description); If( retValue = OBEX_NO_CONNECTION) { /* Connection is already broken */ } InBOX Server APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 53 InBOX Server Callback Functions The following section explains the callback functions used by the OBEX Server to notify the InBOX Server application of incoming requests and events from the Client. The Server application must register the set of callbacks using the ObexRegisterInBoxServer() API. The server application must save the parameters received from the Callback functions before the function returns. Table 8 lists the InBOX Server callback functions used by the OBEX server. Jump to the links provided below for quick reference. Table 8. InBOX Server Callback Functions ObexConnectServerInd() ObexPutServerInd() ObexGetServerInd() ObexAbortServerInd() ObexDisconnectServerInd() The descriptions of the InBOX Server callback funtions begin on the next page. RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 54 ObexConnectServerInd() #include "zobx_api.h" OBEX_CALLBACK_RET ObexConnectServerInd( UINT8 requestIdentifier, OBEX_DEVICE_ID deviceId, UINT16 UINT16 clientMaxPktLen, UINT16 UINT16 *serverMaxPktLen, UINT32 UINT32 objCount, UINT32 UINT32 objLength, INT8 *description, INT8 *friendlyName); Description This is a callback function that notifies the application whenever a CONNECT request is received from the peer. The application fills the serverMaxPktLen parameter passed by the OBEX Server if it does not call ObexServerConnectResponse() API. Arguments requestIdentifier Unique ID given by the OBEX Server to the Application. deviceId Destination device's ID. clientMaxPktLen Maximum Packet Length sent by the Client (acceptable to the remote peer). InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 55 serverMaxPktLen Maximum Packet Length that the server can receive. This variable is initialized to zero and is sent to the application to provide the maximum packet length it can support. If the application does not call the ObexConnectserverResponse() it is useful for the OBEX Server to know the maximum Packet Length supported by the Application through this callback. description Optional description about the Object (as received from the remote peer). friendlyName Name of the destination device. Return Values OBEX_CB_PROCEED Indicates that the application allows OBEX Server to send a successful Connect Response automatically. OBEX_CB_WAIT_FOR_RESPONSE Indicates that OBEX Server must wait for the corresponding ObexConnectServerResponse () API call. OBEX_CB_FATAL_ERROR Indicates fatal application failure and is not able to handle the connection request. Comments The serverMaxPktLen parameter is initialized to zero and passed to the application to return the maximum length it can support in case the application does not call the ObexConnectServerResponse() API call. Example Called from within an OBEX execution context: UINT16 UINT16 clientMaxPktLen = recived_data.peerlen; UINT16 UINT16 srvrPktLen; RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 56 UINT8* friendlyName = discovery_log.friendlyName; UINT32 UINT32 deviceId = destinationDeviceId; /* OBEX Server generates a unique Id when the connect request is received from the client */ UINT8 requestId = GenerateRequestId(); OBEX_CALLBACK_RET obexConnIndRetValue; /* this callback function builds a suitable message and delivers to the application, per porting & implementation guidelines of the product/device */ obexConnIndRetValue = ObexConnectServerInd(requestId, deviceId, clientMaxPktLen, &srvrMaxPktLen, NULL, friendlyName); If( obexConnIndRetValue = OBEX_WAIT_FOR_RESPONSE) { obex_next_substate=WAIT_FOR_CONNECTION_RESPONSE; /* OBEX Server waits for Server Application to call ObexConnectServerResponse() API */ } If( obexConnIndRetValue = OBEX_CB_PROCEED) { obex_next_substate = OBEX_CONNECTED; /* OBEX Server autoamtically sends a successful OBEX Connect Response and wil be waiting to receive incoming PUT/GET/DISCONNECT requests*/ } If(obexConnIndRetValue = OBEX_FATAL_ERROR) InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 57 { obex_next_substate = ABNORMAL_TERMINATION; } See Also ObexConnectServerResponse() ObexStartClientTransaction() RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 58 ObexPutServerInd() #include "zobx_api.h" OBEX_CALLBACK_RET ObexPutServerInd( UINT8 requestIdentifier, INT8 *objectName, INT8 *mimeType, UINT8 *putData, UINT32 UINT32 maxObjLen, UINT16 UINT16 curPktLen, INT8 *description, PUT_STATUS_CODE status ); Description ObexPutServerInd is a callback function that notifies the Application whenever a PUT request is received from the Client. Arguments requestIdentifier Unique identifier, which identifies the request with the corresponding response from the Server. objectName Name of the object. mimeType Type of the object. putData Actual object received from the peer. maxObjLen Length of the Total object. curPktLen Length of the packet currently being sent. description Optional description about the Object. InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 59 status Indicates whether the Transfer is complete or not Possible values are: · OBEX_CREATE: Indicates that the Server application should create an empty object. · OBEX_DELETE: Indicates that the named object has to be deleted if it exists. · OBEX_PUT_MORE_DATA_TO_COME: Indicates there are pending PUT requests from the Client · OBEX_PUT_NO_MORE_DATA_TO_COME: Indicates that this is last packet of the object Return Values OBEX_CB_PROCEED Indicates that the application allows the ZirDA stack to proceed with the PUT response automatically. OBEX_CB_WAIT_FOR_RESPONSE Indicates that the OBEX Server must wait for the corresponding ObexPutServerResponse() API call. OBEX_CB_FATAL_ERROR Indicates fatal application failure and is not able to handle the PUT request. Comments The Server can call this callback many times when an object to be transferred is very large. Therefore, parameters such as object name, type, and MaxPacketLen sent after the first instance are subsequently NULL. Examples Case 1: In this scenario, the Server is expecting more packets from the Client and the status variable is set to OBEX_PUT_MORE_DATA_TO_COME. RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 60 OBEX_CALLBACK_RET retValue; UINT8 requestId = GenerateRequestId(); /* Unique ID given by the Server for this request */ PUT_STATUS_CODE statusCode = OBEX_PUT_MORE_DATA_TO_COME; retValue = ObexPutServerInd( requestId, objectName, objectType, data, maxObjLen, curPktLen, description, statusCode); If(retValue = OBEX_CB_WAIT_FOR_RESPONSE) { /* OBEX Server is waiting for the Server Application to call PutServerResponse API call*/ obex_next_state = OBEX_WAIT_FOR_SERVER_RESPONSE; } else if(retValue = OBEX_CB_PROCEED) { obex_next_state = OBEX_CONNECTED; /* State change comes and OBEX sends the response to the client Application */ } else if(retValue = OBEX_FATAL_ERROR) { obex_next_state = OBEX_ABNORMAL_TERMINATION; } Case 2: In this case, the client has requested the Server to create an empty object before actually sending the data. PUT_STATUS_CODE statusCode = OBEX_CREATE; InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 61 retValue = ObexPutServerInd( requestId, objectName, objectType, data, maxObjLen, curPktLen, description, statusCode); If(retValue = OBEX_CB_WAIT_FOR_RESPONSE) { /* OBEX Server is waiting for the Server Application to call PutServerResponse API call */ obex_next_state = OBEX_WAIT_FOR_SERVER_RESPONSE; } else if(retValue = OBEX_CB_PROCEED) { obex_next_state = OBEX_CONNECTED; /* State change comes and OBEX sends the response to the client Application */ } else if(retValue = OBEX_FATAL_ERROR) { obex_next_state = OBEX_ABNORMAL_TERMINATION; } Case 3: In this case, the client has requested the Server to delete an object. PUT_STATUS_CODE statusCode = OBEX_DELETE; retValue = ObexPutServerInd( requestId, objectName, objectType, data, maxObjLen, curPktLen, RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 62 description, statusCode); If(retValue = OBEX_CB_WAIT_FOR_RESPONSE) { /* OBEX Server is waiting for the Server Application to call PutServerResponse API call */ obex_next_state = OBEX_WAIT_FOR_SERVER_RESPONSE; } else if(retValue = OBEX_CB_PROCEED) { obex_next_state = OBEX_SEND_RESPONSE; /* State change comes and OBEX sends the response to the client Application */ } else if(retValue = OBEX_FATAL_ERROR) { obex_next_state = OBEX_ABNORMAL_TERMINATION; } Case 4: In this scenario, the Server is expecting the last packet from the Client, and the status variable is set to OBEX_NO_MORE_DATA. OBEX_CALLBACK_RET retValue; UINT8 requestId = requestId; /* Request Id generated earlier for the same object transfer*/ PUT_STATUS_CODE statusCode = OBEX_NO_MORE_DATA; retValue = ObexPutServerInd( requestId, objectName, objectType, data, maxObjLen, curPktLen, description, statusCode); InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 63 If(retValue = OBEX_CB_WAIT_FOR_RESPONSE) { /* OBEX Server is waiting for the Server Application to call PutServerResponse API call*/ obex_next_state = OBEX_WAIT_FOR_SERVER_RESPONSE; } else if(retValue = OBEX_CB_PROCEED) { obex_next_state = OBEX_CONNECTED; /* State change comes and OBEX sends the response to the client Application and will be waiting to recieve incoming requests if any */ } else if(retValue = OBEX_FATAL_ERROR) { obex_next_state = OBEX_ABNORMAL_TERMINATION; } See Also ObexInboxPut() PUT_STATUS_CODE ObexPutServerResponse() RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 64 ObexGetServerInd() #include "zobx_api.h" OBEX_CALLBACK_RET ObexGetServerInd( UINT8 requestIdentifier, INT8 *objectName, INT8 *objectType, UINT16 UINT16 maxPktLen, INT8 *description); Description ObexGetServerInd is a callback function that notifies the application whenever a GET request is received from the peer. The OBEX Server waits for a response from the Server application. This response contains a response Identifier that is the same as the requestIdentifier passed here. Arguments requestIdentifier Unique identifier, which identifies the request with the corresponding response from the Server. objectName Name of the object (present for IrMC objects that are accessed by InBOX; for all other InBOX operations it is NULL). objectType MIME Type of the object (Null terminated string). maxPktLen The maximum packet length that the Client can receive while sending the data back to the Client, the Server application must not cross this limit. description Optional description about the Object. InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 65 Return Values OBEX_CB_WAIT_FOR_RESPONSE Indicates that OBEX must wait for the corresponding ObexGetServerResponse() API call. OBEX_CB_FATAL_ERROR Indicates fatal application failure and is not able to handle the Get request. Comments The Server can call the ObexGetServerInd() callback many times when an object to be transferred is very large. Therefore, after the Server passes the type and description of an object in the first instance, these parameters are subsequently NULL. Example INT8 objectType[MAX_LEN] receivedData.objType; INT8 description[MAX_DESC_LEN] = receivedData.objDesc; INT8 objectName[] = receivedData.objectName; UINT8 requestId; UINT16 UINT16 maxPktLen = clientMaxPktLen; OBEX_CALLBACK_RET retValue; retValue = ObexGetServerInd( requestId, objectName, objectType, maxPktLen, description); If(retValue = OBEX_CB_WAIT_FOR_RESPONSE) { /* OBEX Server is waiting for the Server Application to call ObexGetServerResponse API call*/ obex_next_state = OBEX_WAIT_FOR_SERVER_RESPONSE; } else RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 66 { obex_next_state = OBEX_ABNORMAL_TERMINATION; } See Also ObexInboxGet() ObexGetServerResponse() InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 67 ObexAbortServerInd() #include "zobx_api.h" OBEX_CALLBACK_RET ObexAbortServerInd( UINT8 requestIdentifier, INT8 *description); Description ObexAbortServerInd is a callback function that notifies the applica- tion whenever the Abort request is received from the Client. Arguments requestIdentifier ID provided by the Server to match a request and its response. If the Abort comes in the middle of a Put request, the ID must be same as the ID used in the previous Put requrest. description Optional description about the Abort request received from Client. Return Values OBEX_CB_PROCEED OBEX_CB_WAIT_FOR_RESPONSE Indicates that OBEX Server must wait for the corresponding ObexAbortServerResponse( ) API call. OBEX_CB_FATAL_ERROR RM000504-0404 RM000504-0404 Indicates that the Server application allows the OBEX Server to send the Abort response automatically. Indicates fatal application failure and is not able to handle the Abort request. InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 68 Example The example shows that while the PUT operation is in process, the ABORT request comes through. OBEX_CALLBACK_RET retValue; PUT_STATUS_CODE statusCode = OBEX_PUT_MORE_DATA_TO_COME; UINT8 requestId = GenerateRequestId(); retValue = ObexPutServerInd( requestId, objectName, objectType, data, maxObjLen, curPktLen, description, statusCode); if(retValue = OBEX_CB_PROCEED) { obex_next_state = OBEX_CONNECTED; /* State change comes and OBEX sends the response to the client Application and will be in a state to receive incoming requests*/ } Now the Abort request Indication INT8 desc[] = receivedData.desc; RequestId should be same as the one given in the above PUT example. retValue = ObexAbortServerInd(requestId, desc); If(retValue = OBEX_CB_PROCEED) { /* Server will proceed in sending the Abort response packet*/ } else if(retValue = OBEX_CB_WAIT_FOR_RESPONSE) { /* The Server will be waiting for the application to call the AbortServerResponse API */ InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 69 } See Also ObexAbort() ObexAbortServerResponse() RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 70 ObexDisconnectServerInd() #include "zobx_api.h" OBEX_CALLBACK_RET ObexDisconnectServerInd( UINT8 requestIdentifier, OBEX_DISC_REASON discReason, INT8 *description); Description This is a callback function that notifies the Application whenever a Disconnect request is received from the peer. The same callback notifies the Application when any kind of failure occurs at the lower layers. Arguments requestIdentifier Unique value that matches the request and the corresponding response between OBEX Server and the Application. discReason Reason code to disconnect. description Optional description about the Disconnect request. Return Values OBEX_CB_PROCEED Indicates that the Server application allows the OBEX Server to automatically send a successful Disconnect Response to the client. OBEX_CB_WAIT_FOR_RESPONSE Indicates that OBEX must wait for the corresponding ObexDisConnectServerRespo nse() API. InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 71 OBEX_CB_FATAL_ERROR Indicates fatal application failure and is not able to handle the disconnect request. Comments The server can call this callback at any time-not only for when the incoming Disconnect request from the Client, but also when a failure occurs at lower layers. The Server notifies the application using this callback with an appropriate description. The request identifier is used to indicate the application in case any failures occur in the middle of any PUT or GET request apart from the original Disconnect request from the peer. For example, an application is expecting a request from the peer for the PUT operation and is waiting with the request identifier when a failure occurs at the lower layer. The OBEX Server uses the request identifier to notify the application of the disconnect so that the application can choose the action to be taken for the earlier PUT data received. Example INT8 description[MAX_DESC_LEN] = receivedData.description; OBEX_CALLBACK_RET retValue; UINT8 reqId = generateReqId(); retValue = ObexDisconnectServerInd( reqId, OBEX_USER_DISCONNECT,description); If(retValue = OBEX_CB_PROCEED) { /* OBEX Server sends back a successful Disconnect response to the client and will be in a state to wait for the incoming connect requests. */ } /* state changes to OBEX_DISCONNECTED; else if(retValue = OBEX_CB_WAIT_FOR_RESPONSE) { obex_next_state = OBEX_WAIT_FOR_SERVER_RESPONSE; RM000504-0404 RM000504-0404 InBOX Server Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 72 /* Waits for the Server Application to call the ObexDisconnectServerResponse() API */ } See Also ObexEndClientTransaction() OBEX_DISC_REASON ObexDisconnectServerResponse() InBOX Server Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 73 InBOX Client APIs This section describes all of the Client APIs in detail. Only one Client application can be active at any given time. Table 9 lists the InBOX Client APIs. Jump to the links provided below for quick reference. Table 9. InBOX Client APIs ObexDiscoverDevices() ObexStartClientTransaction() ObexInboxPut() ObexInboxGet() ObexAbort() ObexEndClientTransaction() The InBOX Client API descriptions begin on the next page. RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 74 ObexDiscoverDevices() #include "zobx_api.h" OBEX_RET ObexDiscoverDevices ( OBEX_DSCVR_CALLBACK_FUNC dscvrCB); Description This API discovers all of the devices that exist in the communication medium and notifies the application of this list of devices through the callback function that is passed as the parameter. Arguments dscvrCB Pointer to the callback function (OBEX_DSCVR_CALLBACK_FUNC)type Return Values OBEX_SUCCESS OBEX_FAILURE Indicates the failure because of unknown or other reasons. OBEX_INVALID_ARG Indicates the passed argument is NULL or invalid. OBEX_BUSY Indicates that the request cannot be processed temporarily. OBEX_FAILED_BELOW If error occurs at the lower layers. OBEX_NOT_REGISTERED If the application does not call ObexRegisterInboxServer() API before. OBEX_IRDA_INACTIVE InBOX Client APIs Indicates that the function returned successfully. Indicates that the ZirDA Stack is not activated. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 75 Example OBEX_CALLBACK_RET DiscoveryConfirm(OBEX_DISCOVERY_LOG * discovery_log_s); OBEX_RET retValue; retValue = ObexDiscoverDevices(DiscoveryConfirm); if(retValue = OBEX_SUCCESS) { /* Application can wait for the discovery confirmation from the other end */ } elseif( retValue = OBEX_BUSY ) { /* OBEX Client is busy processing other requests */ } else if( retValue = OBEX_INVALID_ARG) { /* The passed parameter could be NULL, application must call the API again */ } See Also ObexDiscoverClientCfm() (type defined as OBEX_DSCVR_CALLBACK_FUNC) RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 76 ObexStartClientTransaction() #include "zobx_api.h" OBEX_RET ObexStartClientTransaction( OBEX_HNDL *hndl, OBEX_DEV_ID deviceId, UINT32 UINT32 objectCount, UINT32 UINT32 totalLenOfAllObjects, UINT16 UINT16 maxPktLen, INT8 *desc, OBEX_CLIENT_CALLBACK_FUNC *clientCB ); Description The ObexStartClientTransaction API allows the Client application to begin a transaction with another device. If the lower layer connection does not exist, it first establishes the connection, then the OBEX connection is made. Arguments hndl A unique Handle returned to the application by the OBEX Client. deviceId 32-bit Destination Device ID. objectCount Number of objects sent during this connection. totalLenOfAllObjects Approximate Length of all objects. maxPktLen desc InBOX Client APIs Indicates the Max Packet Length that the device can receive. Description about the Connect Request passed by the application. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 77 clientCB Pointer to the structure containing the addresses of Connect and Disconnect callback functions. Return Values OBEX_SUCCESS Indicates that the function returned successfully. OBEX_FAILURE Indicates the failure because of unknown or other reasons. OBEX_INVALID_ARG Indicates the passed argument is NULL or invalid. OBEX_BUSY Indicates that the request cannot be processed temporarily. OBEX_UNABLE_SEND_MSG Indicates that the message was not sent. OBEX_MEM_ALLOC_FAILURE Indicates that an error encountered while allocating memory. OBEX_OVERSIZED_DATA Indicates that the packet length exceeds the allowed maximum packet length (255) for the Connect request OBEX_IRDA_INACTIVE Indicates that the IrDA Stack is not activated. Comments Any successful or failed OBEX Connection results in a notification to the Client application via the ConnectCfm callback provided by the application. If any failure occurs at the lower layers (IrLAP/TTP) that hinders OBEX from establishing a connection, the Client application is notified via the DisconnectCfm callback. Example #define OBJECT_LEN 4000 #define OBJECT_CNT 4 RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 78 #define OBEX_MAX_PKT_LEN 2000 OBEX_RET retValue; UINT32 UINT32 objectLen = OBJECT_LEN; UINT32 UINT32 objectCnt = OBJECT_CNT; UINT16 UINT16 maxPktLen = OBEX_MAX_PKT_LEN; OBEX_DEVICE_ID deviceId; OBEX_CALLBACK_RET ObexConnCfm (OBEX_HNDL hndl, UINT16 UINT16 maxPktLen, CONNECT_RESPONSE_CODE rspCode, INT8* description); VOID ObexDiscCfm( OBEX_HNDL hndl, OBEX_DISC_REASON discReason, INT8* description); OBEX_CLIENT_CALLBACK_FUNC clientCB = { ObexConnCfm; ObexDiscCfm; }; OBEX_HNDL hndl; retValue = ObexStartClientTransaction( &hndl, deviceId, objectCnt, objectLen, maxPktLen, NULL, &clientCB); If (retValue = OBEX_SUCCESS) { /* Application can wait for the Confirmation to come from the other end */ } else { /* The connection failed at the lower layers */ InBOX Client APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 79 /* In all of the other cases Application needs to call the API again */ }. Case2: If callback function addresses for StartClientTransaction and EndClientTransaction are NULL, OBEX Client returns an Error OBEX_INVALID_ARG OBEX_CLIENT_CALLBACK_FUNC clientCB = { NULL; DisconnectConfirmation; }; OBEX_HNDL hndl; retValue = , objectLen,maxPktLen,NULL,&clientCB); if (retValue = OBEX_INVALID_ARG) { /* Passed parameters are invalid or incomplete*/ } See Also ObexStartClientCfm() ObexEndClientTransaction() OBEX_CLIENT_CALLBACK_FUNCStructure RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 80 ObexInboxPut() #include "zobx_api.h" OBEX_RET ObexInboxPut( OBEX_HNDL hndl, UINT8 requestIdentifier, INT8 *objectName, INT8 *objectType, INT8 * desc, UINT32 UINT32 maxObjLen, UINT8 *data, UINT16 UINT16 dataLen, PUT_STATUS_CODE status OBEX_CL_PUT_CFM putCfm ); Description The ObexInboxPut API allows the Client application to send the object to the other end. When the response is received from the other end, the other end is notified via the callback. If the object sent is very large, then the application must call this API repeatedly until the object is completely sent. Arguments hndl requestIdentifier Client application supplied unique ID for each PUT request. If more PUT requests are being sent for the same object, the number must be the same for all of the PUT requests. objectName InBOX Client APIs A unique handle returned to the application by the OBEX Client. Name of the Object. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 81 objectType MIME type of the object if required. desc Description about the PUT request passed by the application. maxObjLen Length of the whole object. data Actual data to be sent. dataLen Length of the data currently being sent. status Indicates the status of data transfer (last packet or still to send). The possible values are: OBEX_CREATE OBEX_DELETE Delete an object. OBEX_PUT_NO_MORE_ DATA_TO_COME Indicates that the data is still pending. OBEX_PUT_MORE_DATA_ TO_COME putCfm Create an empty object. Indicates that this is the last packet being sent. Application's callback function address for the PUT operation. Return Values OBEX_SUCCESS OBEX_FAILURE Indicates the failure because of unknown or other reasons. OBEX_INVALID_ARG Indicates the passed argument is NULL or invalid. OBEX_BUSY Indicates that the request cannot be processed temporarily. OBEX_UNABLE_SEND_MSG Indicates the message was not sent. OBEX_MEM_ALLOC_FAILURE RM000504-0404 RM000504-0404 Indicates that the function returned successfully. Indicates an error encountered while allocating memory. InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 82 Comments Because the PUT request comes from the application many times for one object, the application is not required to send the name, the type, and the total length of the object every time. These parameters are required for the first PUT request and can be NULL for subsequent operations. Example OBEX_RET retValue; INT8 objectName[] = "IrDA_UM.txt"; UINT16 UINT16 maxPacketLen; UINT16 UINT16 curPacketlen; UINT8 data[]; OBEX_HNDL hndl; INT8 requestId =GenerateRequestId(); /* Unique ID generated by the application for the request */ PUT_STATUS_CODE statusCode = OBEX_ PUT_MORE_DATA_TO_COME; OBEX_CALLBACK_RET ObexPutClientCfm(OBEX_HNDL, hndl,UINT8 responseId,PUT_STATUS_CODE responseCode,INT8* description,); Case 1: In this case this is the first PUT request to be sent when the total number of packets are four. retValue = ObexInboxPut( hndl, requestId, objectName, NULL, NULL, maxPacketLen, data, curPacketlen, OBEX_PUT_MORE_DATA_TO_COME, ObexPutClientCfm); The status code OBEX_MORE_DATA_TO_COME indicates that the InBOX Client APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 83 whole data is not being transferred in this request. Case 2: This example shows that this is the last PUT request from the application for the object. The variable status OBEX_NO_MORE_DATA_TO_COME indicates the end of transfer. requestId = 1; PUT_STATUS_CODE statusCode = OBEX_PUT_NO_MORE_DATA_TO_COME; retValue = ObexInboxPut( hndl, requestId, objectName, NULL, NULL, maxObjLen, data, curPacketLen, statusCode, PutClientCfm); if( retValue != OBEX_SUCCESS ) { /* Call the API again with valid arguments */ } See Also ObexPutClientCfm() (type defined as OBEX_CL_PUT_CFM) PUT_STATUS_CODE RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 84 ObexInboxGet() #include "zobx_api.h" OBEX_RET ObexInboxGet( OBEX_HNDL hndl, UINT8 requestIdentifier, INT8 *objectName, INT8 *objectType, INT8 *desc, OBEX_CL_GET_CFM getCfm); Description The ObexInboxGet API allows the Client application to get the requested object from the Server application. When the response is received from the other end, the Client application is notified via the callback. Arguments hndl requestIdentifier A unique ID provided by the application to the OBEX Client. This number must be the same for all incoming GET requests for the same object. The OBEX Client returns the same number while reporting to the application via the ObexGetClientCfm() callback when the response is received from the Server. objectName Name of the Object requested (provided for the IrMC objects that are accessed through InBOX). objectType InBOX Client APIs A unique handle returned to the application by the OBEX Client. MIME type of the Object. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 85 desc Description about the GET request passed by the application. getCfm Confirmation Callback function address for the GET request. Return Values OBEX_SUCCESS Indicates that the function returned successfully. OBEX_FAILURE Indicates the failure because of unknown or other reasons. OBEX_INVALID_ARG Indicates the passed argument is NULL or invalid. OBEX_BUSY Indicates that the request cannot be processed temporarily. OBEX_FAILED_BELOW Indicates the failure at the lower layers. Comments If this API must be called many times for the same object (large GET object), the last parameter, getCfm, could be NULL for subsequent GET requests. However, it is mandatory to provide this parameter for the very first GET request. Example Case1: The final parameter getCfm is NULL. OBEX_RET retVal; INT8* objectType; INT8* objectName = NULL; UINT8 requestId = GenerateRequestId(); OBEX_HNDL hndl; /* Handle received at the time of connection */ retVal = ObexInboxGet ( hndl, requestId, RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 86 objectName, objectType, NULL, NULL); If(retVal = OBEX_INVALID_ARG) { /* Application needs to call the API again */ } Case 2: All of the Parameters passed are correct. OBEX_RET retVal; INT8* objectType; UINT8 requestId = 1; OBEX_HNDL hndl; /* Handle received at the time of connection */ retVal = ObexInboxGet ( hndl, requestId, objectName, objectType, NULL, clGetCfms); If(retVal = OBEX_SUCCESS) { /* The request has been sent to the other end successfully */ } See Also ObexGetClientCfm() (type defined as OBEX_CL_GET_CFM) ObexGetServerResponse() InBOX Client APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 87 ObexAbort() #include "zobx_api.h" OBEX_RET ObexAbort( OBEX_HNDL hndl, UINT8 requestIdentifier, INT8 *desc, OBEX_CL_ABORT_CFM abortCfm ); Description The ObexAbort API allows the Client application to Abort any PUT or GET operation that is in process. Arguments hndl A unique handle returned to the application by the OBEX Client. requestIdentifier Refers to the same ID used in the previous PUT/GET request that should be aborted. desc Description about the Abort request passed by the application. abortCfm The application callback function address for the Abort operation. Return Values OBEX_SUCCESS OBEX_FAILURE RM000504-0404 RM000504-0404 Indicates that the function returned successfully. Indicates the failure because of unknown or other reasons. InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 88 OBEX_INVALID_ARG Indicates the passed argument is NULL or invalid. OBEX_MEM_ALLOC_FAILURE Indicates that an error occured while allocating memory. OBEX_UNABLE_SEND_MSG Indicates that the message was not sent. Comments Send the desc argument (optional). Example The OBEX Client is in the process of sending multiple PUT requests and the ABORT request is being sent in between to stop the transaction. OBEX_RET retValue ; INT8 objectName[]; UINT16 UINT16 maxPacketLen; UINT16 UINT16 curPacketLen; UINT8 data[]; OBEX_HNDL hndl; INT8 requestId =1; PUT_STATUS_CODE statusCode = OBEX_MORE_DATA_TO_COME; OBEX_CALLBACK_RET PutClientCfm(OBEX_HNDL hndl, UINT8 responseId, PUT_STATUS_CODE responseCode, INT8* description,); OBEX_CALLBACK_RET AbortClientCfm( OBEX_HNDL hndl, ABORT_STATUS_CODE responseCode, INT8* description) Case 1: retValue = ObexInboxPut( hndl, objectName, NULL, NULL, InBOX Client APIs RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 89 maxPacketLen, data, curPacketLen, statusCode, NULL, requestId); The statusCode OBEX_MORE_DATA_TO_COME indicates that not all of the data is being transferred in this request. Case 2: The Client has received a successful response from the server, but the client must abort the operation. The request ID should be same as the request ID present in the previous PUT request. requestId = previousPUTrequest.requestId; OBEX_RET retVal = ObexAbort( hndl, requestId, description, AbortClientCfm); If(retVal != OBEX_SUCCESS) { /* Application needs to call the API again */ } else { /* Successfully sent the Abort packet */ } See Also ObexAbortClientCfm() (type defined as OBEX_CL_ABORT_CFM) RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 90 ObexEndClientTransaction() #include "zobx_api.h" OBEX_RET ObexEndClientTransaction( OBEX_HNDL hndl INT8 * desc); Description The ObexEndClientTransaction API allows the Client application to close a transaction with another device. However, if other applications are actively using the link, the lower layer connection is not disconnected. Arguments hndl A unique handle returned to the application by the OBEX Client as part of a previous ObexStartClientTransaction() successful API call. desc Descriptive reason for a disconnect Request (end client transaction) passed by the application (optional). Return Values OBEX_SUCCESS OBEX_FAILURE Indicates a failure because of unknown or other reasons. OBEX_INVALID_ARG Indicates the passed argument is NULL or invalid. OBEX_BUSY Indicates that the request cannot be processed temporarily. OBEX_UNABLE_SEND_MSG InBOX Client APIs Indicates that the function returned successfully Indicates that the message was not sent. RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 91 OBEX_MEM_ALLOC_FAILURE Indicates that an error occured while allocating memory. Example INT8 description[MAX_DESC_LEN]; OBEX_RET retValue; OBEX_HNDL hndl; /* Handle received at the time of connection */ retValue = ObexEndClientTransaction( hndl,description); If(retValue != OBEX_SUCCESS) { /* Application needs to call the API again */ } else { /* OBEX Client had sent the Disconnect request to the Server successfully and is waiting to receive a confirmation from the server */ } See Also ObexEndClientCfm() ObexStartClientTransaction() RM000504-0404 RM000504-0404 InBOX Client APIs eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 92 OBEX Client Callback Functions This section explains all of the callbacks callable from the OBEX Client to the application whenever the response comes from the Server. The Client application must register the callbacks with the OBEX Client while calling the appropriate API. The server application must save the parameters received from the Callback functions before the function returns. Table 10 lists the OBEX Client callback function APIs. Jump to the links provided below for quick reference. Table 10. OBEX Client Callback Functions ObexDiscoverClientCfm() ObexStartClientCfm() ObexPutClientCfm() ObexGetClientCfm() ObexAbortClientCfm() ObexEndClientCfm() The descriptions of the OBEX Client callback funtion APIs begin on the next page. OBEX Client Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 93 ObexDiscoverClientCfm() #include "zobx_api.h" OBEX_CALLBACK_RET ObexDiscoverClientCfm( OBEX_DISCOVERY_LOG * fp_discovery_log_s) Description ObexDiscoverClientCfm is a callback function that notifies the appli- cation whenever responses are received from the other devices that exist in the communication medium. Arguments fp_discovery_log_s A pointer to the structure OBEX_DISCOVERY_LOG, which contains the details about the device. Return Values OBEX_SUCCESS Indicates that the function returned successfully. OBEX_FAILURE Indicates failure due to unknown or other reasons. Example #define OBEX_DISCOVERED_DEVICES 2 OBEX_DISCOVERY_LOG obxDscvLog; OBEX_CALLBACK_RET retValue; obxDscvLog.noOfdevices = OBEX_DISCOVERED_DEVICES; For(index = 0; index < OBEX_DISCOVERED_DEVICES;index+) { obxDscvLog.deviceInfo[index].deviceId = deviceId; obxDscvLog.deviceInfo[index].hints[0] = hints[0]; obxDscvLog.deviceInfo[index].hints[1] = hints[1]; obxDscvLog.deviceInfo[index].charSet= b_char_set; strcpy(obxDscvLog.deviceInfo[index].name,b_name); RM000504-0404 RM000504-0404 OBEX Client Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 94 } retValue = ObexDiscoverClientCfm(&disc_log_s); See Also ObexDiscoverDevices() OBEX_DISCOVERY_LOG Structure OBEX Client Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 95 ObexStartClientCfm() #include "zobx_api.h" OBEX_CALLBACK_RET ObexStartClientCfm( OBEX_HNDL hndl, UINT16 UINT16 maxPktLen, CONNECT_RESPONSE_CODE rspCode; INT8 * description); Description ObexStartClientCfm is a callback function that notifies the applica- tion whenever a Client receives a response from the Server for the Connect request. The maxPacketLen parameter indicates the maximum packet size allowed by the Server application. Therefore, whenever a Client sends any data, it must not exceed the limit. Arguments hndl Unique handle provided by Client to the application. maxPktLen Indicates the maximum packet length that the Server can receive. rspCode Indicates the status of connection: OBEX_SUCCESS: OBEX_FAILURE: Server has rejected the connection. OBEX_FORBIDDEN: description Successful connection. Indicates that the request is not accepted, and therefore not serviced. Optional description about the connection. Return Values OBEX_SUCCESS RM000504-0404 RM000504-0404 Indicates that the function returned successfully. OBEX Client Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 96 OBEX_FAILURE Indicates failure due to unknown or other reasons. Example #define MAX_PACKET_LEN 2096 OBEX_CALLBACK_RET retVal; UINT16 UINT16 maxPktLen = MAX_PACKET_LEN; OBEX_HNDL hndl; Case 1: retVal = ObexStartClientCfm( hndl, maxPktLen, OBEX_SUCCESS, NULL); In this case the Server Application has accepted the connect request from the client. Case 2: retVal = ObexStartClientCfm( hndl, maxPktLen, OBEX_FAILURE, NULL); In this case the Server Application has rejected the incoming connect request from the Client. See Also ObexStartClientTransaction() ObexEndClientTransaction() OBEX Client Callback Functions RM000504-0404 RM000504-0404 eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 97 ObexPutClientCfm() #include "zobx_api.h" OBEX_CALLBACK_RET ObexPutClientCfm( OBEX_HNDL hndl, UINT8 responseIdentifier, PUT_STATUS_CODE responseCode, INT8 *description); Description ObexPutClientCfm is a callback function that notifies the application whenever a response is received from the Server for the PUT request. Arguments hndl responseIdentifier RM000504-0404 RM000504-0404 Unique handle passed by the OBEXClient to the application as part of ObexStartClientTransaction() API call. This number should match the requestId passed by the application in the PUT request. OBEX Client Callback Functions eZ80L92/F91/F92 ZirDATM 1.0 IrOBEX API Reference Manual 98 responseCode Response code sent by the Server. Possible response codes are: OBEX_SUCCESS: Indicates the end of object transfer. OBEX_EXPECT_MORE_DATA: Indicates that the server gave permission to the Client to continue sending the rest of the da