Developer

API Reference

IBTImagePullInitiator

Brew Release
Brew MP 1.0.2
Description


Bluetooth Basic Imaging Profile version 1.0, Image Pull Initiator role
This interface allows application to make use of the Image Pull feature defined by Bluetooth BIP specifications. Image Pull application can browse through the images stored on the Imaging Responder device and downloads one or more of them as requested by the user. A typical use case is a mobile phone as Image Pull Initiator and a digital still camera as Imaging Responder.
To provide Image browsing to user, application must perform a number of steps: 1. optionally get the image count, then 2. get the list of image handles, and 3. get individual image properties, and 3. get individual images, and 4. get individual image's thumbnail version 5. get individual image's attachments, if any, and 6. optionally delete individual image
User/application can also choose the one-step-download API, IBTImagePullInitiator_PullImages(), to download a set of images matching a given filtering criteria and their associated thumbnails and attachments without browsing through them first.
For more information, refer to http://bluetooth.com/Bluetooth/Technology/Works/BIP.htm
Usage

Usage example:



   ===== To create an IBTImagePullInitiator object, see instruction in 
         class header file
 
 
   ===== To register signal
   // first create the signals;
   // for example, use ISignalCBFactory_CreateSignal()
   // then register the signals:
   IBTImagePullInitiator_OnEventNotify(piInitiator, piSignal);
 
 
   ===== To retrieve and handle events when Event signal is triggered:
   while (IBTImagePullInitiator_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:
   IBTImagePullInitiator_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 Cellphone";
   IOBEXAuthentication_Config(pMe->piAuth,
                              MIBENUM_CHARSET_US_ASCII,
                              (uint8*)szRealm,
                              STRLEN (szRealm),
                              bUserIDRequired,
                              FALSE, // allow responder only read access
                              TRUE); // config data invalid after next operation
   IOBEXAuthentication_OnResponse(pMe->piAuth, piAuthRespSig);


   ===== To prepare the object for communication with Image Pull responder:
   IBTImagePullInitiator_Config(
      piInitiator, 
      responderBDAddr, 
      0, // server channel unknown in this example
      AEEBT_SEC_SM4_MEDIUM, 
      5); // maximum 5 seconds idle
 

   ===== To find out responder's supported functions:
   IBTImagePullInitiator_GetSupportedFuncs(piInitiator);


   ===== To find out responder's imaging capabilities, if you have a need for them:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_GET_CAPABILITIES)
   {
      IBTImagePullInitiator_GetCapabilities(piInitiator, (IPort1*)piCapFile);
   }


   ===== To get a list of images on the responder:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_GET_IMAGES_LIST)
   {
      IBTImagePullInitiator_GetImagesList(
         piInitiator, 
         5,                      // ask for up to 5 image handles
         nOffset,                // 0-base
         TRUE,                   // just the new images, please
         filteringCriteria,
         (IPort1*)pMe->piImagesListFile);
   }


   ===== To get the properties of an image from the responder:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_GET_IMAGE_PROPERTIES)
   {
      IBTImagePullInitiator_GetImageProperties(
         piInitiator, 
         &pMe->handleArray[pMe->currHandleIdx],
         (IPort1*)piFile);
   }


   ===== To pull an image from responder:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_GET_IMAGE)
   {
      IBTImagePullInitiator_GetImage(
         piInitiator, 
         &pMe->handleArray[pMe->currHandleIdx],
         "",  // use responder's preferred format
         (IPort1*)piFile);
   }


   ===== To pull the thumbnail version of an image from the responder:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_GET_LINKED_THUMBNAIL)
   {
      IBTImagePullInitiator_GetThumbnail(
         piInitiator, 
         &pMe->handleArray[pMe->currHandleIdx],
         (IPort1*)piFile);
   }


   ===== To pull an attachment associated with a given image from the responder:
   // assuming appGetNumAttachments() returns number of attachments
   // associated with an image
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_GET_LINKED_ATTACHMENT)
   {
      int nNumAttachments = 
             appGetNumAttachments(&pMe->handleArray[pMe->currHandleIdx]);
      while (nNumAttachments-- > 0)
      {
         // open a file for each attachment file of interest
         // here we assume pMe->piAttachmentFile[] is the array holding
         // the file objects for these attachment files
         // and pMe->ppwAttachmentName[] is the array holding
         // the pointers to the attachment file names extracted from
         // the image properties object
      }
      IBTImagePullInitiator_GetAttachment(
         piInitiator, 
         &pMe->handleArray[pMe->currHandleIdx],
         pMe->ppwAttachmentName[pMe->currAttachmentIdx],
         (IPort1*)pMe->piAttachmentFile[pMe->currAttachmentIdx]);
      // wait for COMPLETE event before getting the next attachment file
   }


   ===== To delete a given image from the responder:
   if (pMe->cSupportedFuncs & AEEBTBIP_FUNC_DELETE_IMAGE)
   {
      IBTImagePullInitiator_DeleteImage(
         piInitiator, 
         &pMe->handleArray[pMe->currHandleIdx]);
   }


   ===== To pull a collection of images and their associated thumbnail versions
   ===== and attachments from the Image Pull responder in one step:
   if (SUCCESS == ISHELL_CreateInstance(piShell, AEECLSID_FileSystem2, 
                                        &pMe->piFS))
   {
      IBTImagePullInitiator_PullImages(
         piInitiator, 
         10,               // no more than 10 images
         TRUE,             // just the new images
         FALSE,            // don't delete them from responder
         filteringCriteria,
         "fs:/myRxPics/",  // destination folder
         pMe->piFS,
         1000);            // 1000 bytes received between progress report
   }


   ===== 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 IBTImagePullInitiator_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 IBTImagePullInitiator_GetImagesList()
         // eventData.nDescriptorLen holds the length of the string
         //   describing the filtering criteria applied in creating 
         //   images list
         break;
      }
      case AEEBTBIP_FUNC_GET_IMAGE_PROPERTIES:
      {
         // eventData.nSize holds the length of the image properties string
         // which can be extracted from the file object given to
         // the call to IBTImagePullInitiator_GetImageProperties()
         break;
      }
      case AEEBTBIP_FUNC_GET_IMAGE:
         // eventData.nSize is the size of the image which can be 
         // extracted from the file object given to the call to 
         // IBTImagePullInitiator_GetImage()
         break;
      case AEEBTBIP_FUNC_GET_LINKED_THUMBNAIL:
         // eventData.nSize is the size of the thumbnail which can be 
         // extracted from the file object given to the call to 
         // IBTImagePullInitiator_GetThumbnail()
         break;
      case AEEBTBIP_FUNC_GET_LINKED_ATTACHMENT:
         // eventData.nSize is the size of the attachment which can be 
         // extracted from the file object given to the call to 
         // IBTImagePullInitiator_GetAttachment()

         pMe->currAttachmentIdx++;  // prepare to get the next attachment file
         // see sample code above for IBTImagePullInitiator_GetAttachment()
         break;
      case AEEBTBIP_FUNC_DELETE_IMAGE:
         // nothing to do
         break;
   }


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


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


   ===== When done with Image Pull Initiator:
   IBTImagePullInitiator_Release(piInitiator);

   
  • Follow