API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

IBTFTPSERVER

Brew Release
Brew MP 1.0.2
See Also
None
Description

This interface enables the server role of File Transfer profile as defined by the Bluetooth SIG.
When enabling FTP server, application must provide a security level, OBEX authentication level, the server name, root folder path, a file system object, and a bitmask of supported operations. Once enabled, FTP server is ready to accept connection requests from potential FTP clients. Each FTP server object is designed to handle only one connection at a time.
If OBEX authentication is required by the server or initiated by the client, application should expect and handle authentication request before a connection could be set up. Server application can also authenticate individual operations whether or not client has been authenticated at connection time.
When responding to a connection request, application must provide a bitmask of operations it wishes the lower implementation to handle automatically. Requests for operations not listed in the bitmask will be forwarded to the app for approval.
Once a connection is set up, client can send any operation requests. Typically no user interaction is required or expected. Depending on configuration, either the implementation will quietly handle or reject the requests, or it will forward the requests to application. By accepting a request, application does not actually handle the operation, but rather informs lower implementation that the operation is allowed to be carried out. An operation can not start until a previous operation completes.
Usage

To create an IBTFTPServer object, see instruction in the class header file.

** To register a signal:
   // first create the signals;
   // for example, use ISignalCBFactory_CreateSignal()
   // then register the signals:
   IBTFTPServer_OnEventNotify (piBTFTPSrv, piSignal);


** To get an associated IOBEXAuthentication object:
   IBTFTPServer_QueryInterface (piBTFTPSrv, 
                                AEEIID_IOBEXAuthentication,
                                (void**)&pMe->piAuth);

   // Prepare for authentication initiated by FTP client
   IOBEXAuthentication_OnRequest (pMe->piAuth, piAuthReqSig);

   // Prepare to initiate authentication; this tells server object
   // whether the incoming connection request should be authenticated.
   char szRealm[] = "James' Files";
   IOBEXAuthentication_Config(pMe->piAuth,
                              MIBENUM_CHARSET_US_ASCII,
                              (uint8*)szRealm,
                              STRLEN (szRealm),
                              bUserIDRequired,
                              FALSE, // default access is read-only
                              TRUE); // config data invalid after next operation
   IOBEXAuthentication_OnResponse(pMe->piAuth, piAuthRespSig);


** To enable an FTP server and allow read-only access:
   IBTFTPServer_Enable (piBTFTPSrv, AEEBT_SEC_SM4_MEDIUM, 
                        AEEBT_OBEX_AUTH_USERID_AND_PASSWORD,
                        "James' Files", // server's name
                        piFileSys1,     // file system object
                        (AEEBTFTP_OP_GET | AEEBTFTP_OP_BROWSE));
 
 
** To retrieve and handle events when an event signal is triggered:
   while (IBTFTPServer_GetEvent (piBTFTPSrv, &eventData) != AEE_ENOMORE)
   {
      IFilePort1* piTempFile;

      switch (eventData.cEvent)
      {
         case AEEBTFTPSVR_EV_ENABLED:
         case AEEBTFTPSVR_EV_DISABLED:
            // check eventData.cResult to see if it was successful
            break;

         case AEEBTFTPSVR_EV_CONNECTED:
         case AEEBTFTPSVR_EV_DISCONNECTED:
            // check eventData.cResult to see if it was successful
            // eventData.bdAddr identifies the client
            break;

         case AEEBTFTPSVR_EV_CONNECT_REQ:
            AppGetDeviceName (eventData.bdAddr);
            // prompt user "Accept FTP conn req from ?"
            if (FALSE == bUserAccept)
            {
               // reject
               IBTFTPServer_AcceptConnection (
                  piBTFTPSrv, FALSE,
                  AEEBTFTP_OP_NONE); // op bitmap doesn't matter
            }
            else
            {
               IBTFTPServer_AcceptConnection (
                  piBTFTPSrv, TRUE,
                  "fs:/card0",          // root folder
                  AEEBTFTP_OP_BROWSE);  // folder listing automatically handled
            }
            break;
 
         case AEEBTFTPSVR_EV_OP_REQ:
            // should only receive this event if requested operation isn't
            // one to be auto accepted; eventData.opReqInfo.cOp tells 
            // which operation is being requested
            nLen = eventData.opReqInfo.nPathNameLen;
            char* pszPathName = MALLOC (nLen);
            IBTFTPServer_GetPathName (piBTFTPSrv, pszPathName, nLen, &nLen);

            // in this example no authentication is need for getting a file
            // from root folder; any other operation requires authentication
            if ((FALSE != eventData.opReqInfo.bAuthenticated) ||
                ((AEEBTFTP_OP_GET == eventData.opReqInfo.cOp) &&
                 (FALSE != IsRootFolder (pszPathName))))
            {
               IBTFTPServer_AcceptOperation (
                  piBTFTPSrv, 
                  bUserAccept, // user input
                  200); // progress report every 200 bytes (if accepting)
            }
            else
            {
               IOBEXAuthentication_Config(pMe->piAuth, 
                                          MIBENUM_CHARSET_US_ASCII, 
                                          (uint8*) pszPathName, // realm
                                          STRLEN (pszPathName), // realm len
                                          bUserIDRequired,
                                          bFullAccess,
                                          TRUE); // valid once
            }
            break;

         case AEEBTFTPSVR_EV_OP_PROGRESS:
            // eventData.uBytes tells how much data has been sent/received
            break;

         case AEEBTFTPSVR_EV_OP_COMPLETE:
            // check eventData.cResult to see if it was successful
            break;

         case AEEBTFTPSVR_EV_EVENT_Q_OVERFLOW:
            // eventData.nDroppedEvents tells how many events got dropped
            // since previous GetEvent()
            break;
      }
   }
   ISignalCtl_Enable (piSignalCtl); // re-enable signal
 
 
** When done with the FTP server:
   IBTFTPServer_ForceDisconnect (piBTFTPSrv);
   IBTFTPServer_Disable (piBTFTPSrv);
   IBTFTPServer_Release (piBTFTPSrv);