Developer

API Reference

IBTRemoteDisplayInitiator

Brew Release
Brew MP 1.0.2
Description

Bluetooth Basic Imaging Profile version 1.0, Image Push Initiator role
This interface allows application to make use of the Remote Display feature defined by Bluetooth BIP specifications. This feature enables Image initiator to push images to Image responder and control the display sequence of those images. The typical use case is a laptop as Image initiator and a projector as Image responder.
Initiator application can send individual images to responder, remember the handles assigned to them by the responder, and supply these handles to responder in any particular order to be displayed one by one. A list of handles of the images sent to responder can also be retrieved if application chooses not to maintain its own list.
For more information, refer to http://bluetooth.com/Bluetooth/Technology/Works/BIP.htm
Usage

Usage example:



   ===== To create an IBTRemoteDisplayInitiator object, see instruction in 
         class header file
 
 
   ===== To register signal
   // first create the signals;
   // for example, use ISignalCBFactory_CreateSignal()
   // then register the signals:
   IBTRemoteDisplayInitiator_OnEventNotify(piInitiator, piSignal);
 
 
   ===== To retrieve and handle events when Event signal is triggered:
   while (IBTRemoteDisplayInitiator_GetEvent(piInitiator, 
                                             &eventData) != AEE_ENOMORE)
   {
      switch (eventData.cEvent)
      {
         case AEEBTBIPI_EV_CONNECTED:
         case AEEBTBIPI_EV_DISCONNECTED:
            break;

         case AEEBTBIPI_EV_GET_FUNCS_DONE:
            if (AEEBT_RESULT_SUCCESS != eventData.cResult)
            {
               pMe->cSupportedFuncs = eventData.cFunc;
            }
            break;

         case AEEBTBIPI_EV_OP_INITIATED:
            // eventData.cFunc is the function associated with 
            // the operation that just started
            break;

         case AEEBTBIPI_EV_OP_COMPLETED:
            if (AEEBT_RESULT_SUCCESS != eventData.cResult)
            {
               // something went wrong
            }
            else
            {
               appHandleOpComplete(); // see sample code below
            }
            break;

         case AEEBTBIPI_EV_OP_PROGRESS:
            // eventData.cFunc tells the function associated with this op
            // eventData.nSize tells number of data bytes received so far
            break;

         case AEEBTBIPI_EV_EVENT_Q_OVERFLOW:
            // eventData.nSize tells how many events got dropped
            // since previous GetEvent()
            break;
      }
   }
   ISignalCtl_Enable(piSignalCtl); // re-enable signal
 
 
   ===== To get an associated IOBEXAuthentication object:
   IBTRemoteDisplayInitiator_QueryInterface(piInitiator, 
                                            AEEIID_IOBEXAuthentication,
                                            (void**)&pMe->piAuth);

   // prepare for authentication initiated by responder
   IOBEXAuthentication_OnRequest(pMe->piAuth, piAuthReqSig);

   // prepare to initiate authentication; this tells initiator object
   // to authenticate responder prior to initiating the next operation
   char szRealm[] = "James Laptop";
   IOBEXAuthentication_Config(pMe->piAuth,
                              MIBENUM_CHARSET_US_ASCII,
                              (uint8*)szRealm,
                              STRLEN (szRealm),
                              bUserIDRequired,
                              FALSE, // allow projector only read access
                              TRUE); // config data invalid after next operation
   IOBEXAuthentication_OnResponse(pMe->piAuth, piAuthRespSig);


   ===== To prepare the object for communication with Remote Display responder:
   IBTRemoteDisplayInitiator_Config(
      piInitiator, 
      projectorBDAddr, 
      0,   // server channel unknown in this example
      AEEBT_SEC_SM4_HIGH, 
      60); // maximum 60 seconds idle


   ===== To find out projector's supported functions:
   IBTRemoteDisplayInitiator_GetSupportedFuncs(piInitiator);


   ===== To find out projector's imaging capability:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_GET_CAPABILITIES)
   {
      IBTRemoteDisplayInitiator_GetCapabilities(piInitiator, (IPort1*)piCapFile);
   }


   ===== To push an image to the Image Push responder:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_PUT_IMAGE)
   {
      IBTRemoteDisplayInitiator_PutImage(
         piInitiator, 
         (IPort1*) piImageFile,  // result of IFileSystem2_Open()
         szImageDescriptor,
         wImageName,
         NULL);   // no thumbnail version available
   }


   ===== To get a list of images available for display on responder:
   // if application does not keep track of the handles returned by
   // each of the calls to IBTRemoteDisplayInitiator_PutImage(),
   // it can ask responder for it:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_GET_IMAGES_LIST)
   {
      IBTRemoteDisplayInitiator_GetImagesList(
         piInitiator, 
         50,                              // up to 50 images
         0,                               // start from beginning of list
         FALSE,                           // old and new
         "",                              // unfiltered
         (IPort1*)pMe->piImageListFile);  // save the list in this file
   }


   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_REMOTE_DISPLAY)
   {
      ===== To select an image to start the display sequence:
      IBTRemoteDisplayInitiator_SelectImage(piInitiator, pHandle);


      ===== To display the selected image:
      IBTRemoteDisplayInitiator_Display(piInitiator, 
                                        AEEBT_BIP_DISPLAY_CMD_CURRENT);
   }


   ===== sample appHandleOpComplete(eventData):
   switch (eventData.cFunc)
   {
      case AEEBTBIP_FUNC_GET_CAPABILITIES:
      {
         // eventData.nSize holds the length of the capabilities string
         // which can be extracted from the file object given to
         // the call to IBTRemoteDisplayInitiator_GetCapabilities()
         break;
      }
      case AEEBTBIP_FUNC_GET_IMAGES_LIST:
      {
         // eventData.nCount holds the number of image handles returned
         // eventData.nSize holds the length of the listing object
         //   which can be extracted from the file object given to
         //   the call to IBTRemoteDisplayInitiator_GetImagesList()
         // eventData.nDescriptorLen holds the length of the string
         //   describing the filtering criteria applied in creating 
         //   images list
         break;
      }
      case AEEBTBIP_FUNC_PUT_IMAGE:
      {
         // eventData.handle is the image handle assigned by responder
         // this handle is only considered valid until connection is
         // brought down
         break;
      }
      case AEEBTBIP_FUNC_REMOTE_DISPLAY:
      {
         // eventData.handle is the handle of the image currently displayed
         // if eventData.handle is invalid, this was the result of
         // IBTRemoteDisplayInitiator_SelectImage()
         break;
      }
   }


   ===== To cancel the current operation:
   IBTRemoteDisplayInitiator_Cancel(piInitiator);


   ===== To disconnect before the idle timer expires:
   IBTRemoteDisplayInitiator_Disconnect(piInitiator);


   ===== When done with Image Push Initiator:
   IBTRemoteDisplayInitiator_Release(piInitiator);

   
  • Follow