1
0

antfs_host_interface.hpp 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596
  1. /*
  2. This software is subject to the license described in the License.txt file
  3. included with this software distribution. You may not use this file except
  4. in compliance with this license.
  5. Copyright (c) Dynastream Innovations Inc. 2016
  6. All rights reserved.
  7. */
  8. #if !defined(ANTFS_HOST_INTERFACE_H)
  9. #define ANTFS_HOST_INTERFACE_H
  10. #include "types.h"
  11. #include "dsi_thread.h"
  12. #include "antfs_interface.h"
  13. #include "antfsmessage.h"
  14. //////////////////////////////////////////////////////////////////////////////////
  15. // Public Definitions
  16. //////////////////////////////////////////////////////////////////////////////////
  17. #define ANTFS_STATUS1_RESERVED7_BIT ((UCHAR) 0x80)
  18. #define ANTFS_STATUS1_DATA_AVAILABLE_BIT ((UCHAR) 0x20)
  19. #define ANTFS_STATUS1_UPLOAD_ENABLED_BIT ((UCHAR) 0x10)
  20. #define ANTFS_STATUS1_PAIRING_ENABLED_BIT ((UCHAR) 0x08)
  21. #define ANTFS_STATUS1_BEACON2_BIT ((UCHAR) 0x04)
  22. #define ANTFS_STATUS1_BEACON1_BIT ((UCHAR) 0x02)
  23. #define ANTFS_STATUS1_BEACON0_BIT ((UCHAR) 0x01)
  24. #define ANTFS_STATUS2_RESERVED7_BIT ((UCHAR) 0x80)
  25. #define ANTFS_STATUS2_RESERVED6_BIT ((UCHAR) 0x40)
  26. #define ANTFS_STATUS2_RESERVED5_BIT ((UCHAR) 0x20)
  27. #define ANTFS_STATUS2_RESERVED4_BIT ((UCHAR) 0x10)
  28. #define ANTFS_STATUS2_CLIENT_STATE3_BIT ((UCHAR) 0x08)
  29. #define ANTFS_STATUS2_CLIENT_STATE2_BIT ((UCHAR) 0x04)
  30. #define ANTFS_STATUS2_CLIENT_STATE1_BIT ((UCHAR) 0x02)
  31. #define ANTFS_STATUS2_CLIENT_STATE0_BIT ((UCHAR) 0x01)
  32. #define ANTFS_STATUS1_DEFAULT_SEARCH_MASK ((UCHAR) 0x38)
  33. #define ANTFS_STATUS2_DEFAULT_SEARCH_MASK ((UCHAR) 0x00)
  34. // ANT-FS Host Responses
  35. typedef enum
  36. {
  37. ANTFS_HOST_RESPONSE_NONE = 0,
  38. ANTFS_HOST_RESPONSE_INIT_PASS,
  39. ANTFS_HOST_RESPONSE_SERIAL_FAIL,
  40. ANTFS_HOST_RESPONSE_REQUEST_SESSION_FAIL,
  41. ANTFS_HOST_RESPONSE_CONNECT_PASS,
  42. ANTFS_HOST_RESPONSE_DISCONNECT_PASS,
  43. ANTFS_HOST_RESPONSE_CONNECTION_LOST,
  44. ANTFS_HOST_RESPONSE_AUTHENTICATE_NA,
  45. ANTFS_HOST_RESPONSE_AUTHENTICATE_PASS,
  46. ANTFS_HOST_RESPONSE_AUTHENTICATE_REJECT,
  47. ANTFS_HOST_RESPONSE_AUTHENTICATE_FAIL,
  48. ANTFS_HOST_RESPONSE_DOWNLOAD_PASS,
  49. ANTFS_HOST_RESPONSE_DOWNLOAD_REJECT,
  50. ANTFS_HOST_RESPONSE_DOWNLOAD_INVALID_INDEX,
  51. ANTFS_HOST_RESPONSE_DOWNLOAD_FILE_NOT_READABLE,
  52. ANTFS_HOST_RESPONSE_DOWNLOAD_NOT_READY,
  53. ANTFS_HOST_RESPONSE_DOWNLOAD_CRC_REJECTED,
  54. ANTFS_HOST_RESPONSE_DOWNLOAD_FAIL,
  55. ANTFS_HOST_RESPONSE_UPLOAD_PASS,
  56. ANTFS_HOST_RESPONSE_UPLOAD_REJECT,
  57. ANTFS_HOST_RESPONSE_UPLOAD_INVALID_INDEX,
  58. ANTFS_HOST_RESPONSE_UPLOAD_FILE_NOT_WRITEABLE,
  59. ANTFS_HOST_RESPONSE_UPLOAD_INSUFFICIENT_SPACE,
  60. ANTFS_HOST_RESPONSE_UPLOAD_FAIL,
  61. ANTFS_HOST_RESPONSE_ERASE_PASS,
  62. ANTFS_HOST_RESPONSE_ERASE_FAIL,
  63. ANTFS_HOST_RESPONSE_MANUAL_TRANSFER_PASS,
  64. ANTFS_HOST_RESPONSE_MANUAL_TRANSFER_TRANSMIT_FAIL,
  65. ANTFS_HOST_RESPONSE_MANUAL_TRANSFER_RESPONSE_FAIL,
  66. ANTFS_HOST_RESPONSE_CANCEL_DONE
  67. } ANTFS_HOST_RESPONSE;
  68. // ANT-FS Host States
  69. typedef enum
  70. {
  71. ANTFS_HOST_STATE_OFF = 0, // Object created, but not initialized
  72. ANTFS_HOST_STATE_IDLE, // Object initialized
  73. ANTFS_HOST_STATE_DISCONNECTING,
  74. ANTFS_HOST_STATE_REQUESTING_SESSION,
  75. ANTFS_HOST_STATE_SEARCHING, // LINK
  76. ANTFS_HOST_STATE_CONNECTED, // AUTH
  77. ANTFS_HOST_STATE_AUTHENTICATING,
  78. ANTFS_HOST_STATE_TRANSPORT,
  79. ANTFS_HOST_STATE_DOWNLOADING,
  80. ANTFS_HOST_STATE_UPLOADING,
  81. ANTFS_HOST_STATE_ERASING,
  82. ANTFS_HOST_STATE_SENDING,
  83. ANTFS_HOST_STATE_RECEIVING
  84. } ANTFS_HOST_STATE;
  85. typedef struct
  86. {
  87. ULONG ulDeviceID;
  88. USHORT usManufacturerID;
  89. USHORT usDeviceType;
  90. UCHAR ucAuthenticationType;
  91. UCHAR ucStatusByte1;
  92. UCHAR ucStatusByte2;
  93. } ANTFS_DEVICE_PARAMETERS;
  94. //////////////////////////////////////////////////////////////////////////////////
  95. // Public Function Prototypes
  96. //////////////////////////////////////////////////////////////////////////////////
  97. // TODO: Is this class used for anything? Do we need it?
  98. class ANTFSHostInterface
  99. {
  100. public:
  101. virtual ~ANTFSHostInterface(){}
  102. virtual void Close(void) = 0;
  103. /////////////////////////////////////////////////////////////////
  104. // Stops any pending actions, closes all resources and cleans
  105. // up any dynamic memory being used by the library.
  106. /////////////////////////////////////////////////////////////////
  107. virtual ANTFS_HOST_STATE GetStatus(void) = 0;
  108. /////////////////////////////////////////////////////////////////
  109. // Returns the current library status.
  110. /////////////////////////////////////////////////////////////////
  111. virtual ANTFS_HOST_RESPONSE WaitForResponse(ULONG ulMilliseconds_) = 0;
  112. /////////////////////////////////////////////////////////////////
  113. // Wait for a response from the ANTFSHost object.
  114. // Parameters:
  115. // ulMilliseconds_: Set this value to the minimum time to
  116. // wait before returning. If the value is
  117. // 0, the function will return immediately.
  118. // If the value is DSI_THREAD_INFINITE, the
  119. // function will not time out.
  120. // If one or more responses are pending before the timeout
  121. // expires the function will return the first response that
  122. // occured. If no response is pending at the time the timeout
  123. // expires, ANTFS_HOST_RESPONSE_NONE is returned.
  124. /////////////////////////////////////////////////////////////////
  125. virtual void Cancel(void) = 0;
  126. /////////////////////////////////////////////////////////////////
  127. // Cancels any pending actions and returns the library to the
  128. // appropriate ANTFS layer if possible. ie if the library was
  129. // executing a download command in the transport layer, the
  130. // library would be returned to ANTFS_HOST_STATE_TRANSPORT after
  131. // execution of this function.
  132. // A response of ANTFS_HOST_RESPONSE_CANCEL_DONE will be sent
  133. // back to the application when the cancel operation is
  134. // complete.
  135. /////////////////////////////////////////////////////////////////
  136. virtual USHORT AddSearchDevice(ANTFS_DEVICE_PARAMETERS *pstDeviceSearchMask_, ANTFS_DEVICE_PARAMETERS *pstDeviceParameters_) = 0;
  137. /////////////////////////////////////////////////////////////////
  138. // Adds a set of parameters for which to search to the internal
  139. // search device list.
  140. // Parameters:
  141. // *pstDeviceSearchMask_: A pointer to an
  142. // ANTFS_DEVICE_PARAMETERS structure. Set a
  143. // member to zero (0) to wildcard search for
  144. // it. Otherwise, set the bits that you want
  145. // to be matched to 1 in each member. Members
  146. // that are integer values will be treated the
  147. // same as bit fields for the purposes for the mask.
  148. // *pstDeviceParameters_: A pointer to an
  149. // ANTFS_DEVICE_PARAMETERS structure. Set
  150. // the member to the desired search value.
  151. // A member in this structure is ignored if
  152. // the associated member in the
  153. // *pstDeviceSearchMask_ parameter is set
  154. // to zero (0) for wildcard.
  155. // Returns a handle the the search device entry. If the return
  156. // value is NULL, the function failed adding the device entry.
  157. // This means that the device list is already full.
  158. // Operation:
  159. // Note that the default search masks should normally be applied
  160. // to the ucStatusByte1 and ucStatusByte2 members of the
  161. // *pstDeviceSearchMask_ parameter. Eg;
  162. // pstMyDeviceSearchMask->ucStatusByte1 =
  163. // ANTFS_STATUS1_DEFAULT_SEARCH_MASK & ucMyStatus1Criteria;
  164. // Setting bits outside the masks, especially reserved bits, may
  165. // lead to undesired behaviour.
  166. /////////////////////////////////////////////////////////////////
  167. virtual void RemoveSearchDevice(USHORT usHandle_) = 0;
  168. /////////////////////////////////////////////////////////////////
  169. // Removes a device entry from the internal search list.
  170. // Parameters:
  171. // usHandle_: Handle to the device entry to be removed
  172. // from the list.
  173. /////////////////////////////////////////////////////////////////
  174. virtual void ClearSearchDeviceList(void) = 0;
  175. /////////////////////////////////////////////////////////////////
  176. // Clears the internal search device list.
  177. /////////////////////////////////////////////////////////////////
  178. virtual ANTFS_RETURN SearchForDevice(UCHAR ucSearchRadioFrequency_ = ANTFS_RF_FREQ, UCHAR ucConnectRadioFrequency_ = ANTFS_DEFAULT_TRANSPORT_FREQ, USHORT usRadioChannelID_ = 0, BOOL bUseRequestPage_ = FALSE) = 0;
  179. /////////////////////////////////////////////////////////////////
  180. // Begins a search for ANTFS remote devices.
  181. // Parameters:
  182. // ucSearchRadioFrequency_: This specifies the frequency on
  183. // which to search for devices. This
  184. // frequency is calculated as
  185. // (ucSearchRadioFrequency_ * 1 MHz +
  186. // 2400 MHz). MAX_UCHAR (0xFF) is reserved.
  187. // ucConnectRadioFrequency_: This specifies the frequency
  188. // on which the connection communication
  189. // will occur. This frequency is calculated
  190. // as (ucConnectRadioFrequency_ * 1 MHz +
  191. // 2400 MHz). If ucConnectRadioFrequency_
  192. // is set to ANTFS_AUTO_FREQUENCY_SELECTION
  193. // (0xFF), then the library will use an
  194. // adaptive frequency-hopping scheme.
  195. // usRadioChannelID_: This specifies the channel ID for the
  196. // the ANT channel search. Set to zero to
  197. // wildcard.
  198. // bUseRequestPage_: Specifies whether the search will include
  199. // ANT-FS broadcast devices, using a request
  200. // page to begin an ANT-FS session
  201. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  202. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  203. // ANTFS_RETURN_BUSY if the library is busy with another request.
  204. // Operation:
  205. // Once this function is called successfully, the application
  206. // must wait for the response from the ANTFSHost object.
  207. // Possible responses are:
  208. // ANTFS_HOST_RESPONSE_CONNECT_PASS
  209. // ANTFS__HOST_RESPONSE_SERIAL_FAIL
  210. // The library will continue to search for devices until a device
  211. // is found, the Cancel() function is called, an error occurs, or
  212. // the library is closed.
  213. /////////////////////////////////////////////////////////////////
  214. virtual BOOL GetFoundDeviceParameters(ANTFS_DEVICE_PARAMETERS *pstDeviceParameters_, UCHAR *aucFriendlyName_, UCHAR *pucBufferSize_) = 0;
  215. /////////////////////////////////////////////////////////////////
  216. // Copies the parameters of the most recently found device to the
  217. // supplied parameter.
  218. // Parameters:
  219. // *ptsDeviceParameters_: A pointer to a structure that will
  220. // receive a copy of the device parameters.
  221. // *aucFriendlyName_: A pointer to a buffer where the remote
  222. // device friendly name will be copied.
  223. // *pucBufferSize_: Pointer to a UCHAR variable that should contain the
  224. // maximum size of the buffer pointed to by aucFriendlyName_.
  225. // After the function returns, the UCHAR variable
  226. // will be set to reflect the size of friendly name string
  227. // that has been copied to aucFriendlyName_.
  228. // Returns TRUE if successful. Otherwise, it returns FALSE.
  229. /////////////////////////////////////////////////////////////////
  230. virtual BOOL GetUploadStatus(ULONG *pulByteProgress_, ULONG *pulTotalLength_) = 0;
  231. /////////////////////////////////////////////////////////////////
  232. // Gets the transfer progress of a pending or a complete
  233. // upload.
  234. // Parameters:
  235. // *pulByteProgress_: Pointer to a ULONG that will receive
  236. // the current byte progress of a pending or
  237. // complete upload.
  238. // *pulTotalLength_: Pointer to a ULONG that will receive the
  239. // total length of the file being uploaded.
  240. // Returns TRUE if successful. Otherwise, it returns FALSE.
  241. // Operation:
  242. // A data upload occurs when information is requested to be sent to
  243. // a remote device. This function may be called at any point
  244. // during an upload as a progress indicator. After the upload
  245. // is complete, this information is valid until another request
  246. // for a data transfer is made.
  247. /////////////////////////////////////////////////////////////////
  248. virtual BOOL GetDownloadStatus(ULONG *pulByteProgress_, ULONG *pulTotalLength_) = 0;
  249. /////////////////////////////////////////////////////////////////
  250. // Gets the transfer progress of a pending or a complete
  251. // download.
  252. // Parameters:
  253. // *pulByteProgress_: Pointer to a ULONG that will receive
  254. // the current byte progress of a pending or
  255. // complete download.
  256. // *pulTotalLength_: Pointer to a ULONG that will receive the
  257. // total expected length of the download.
  258. // Returns TRUE if successful. Otherwise, it returns FALSE.
  259. // Operation:
  260. // A data download occurs when information is requested from a
  261. // remote device. This function may be called at any point
  262. // during a download as a progress indicator. After the transfer
  263. // is complete, this information is valid until another request
  264. // for a data transfer is made.
  265. /////////////////////////////////////////////////////////////////
  266. virtual BOOL GetTransferData(ULONG *pulDataSize_ , void *pvData_ = NULL) = 0;
  267. /////////////////////////////////////////////////////////////////
  268. // Gets the received data from a transfer (download/manual transfer).
  269. //
  270. // Parameters:
  271. // *ulDataSize_ : Pointer to a ULONG that will receive
  272. // the size of the data available in bytes.
  273. // *pvData_ : Pointer to a buffer where the received data
  274. // will be copied. NULL can be passed to this
  275. // parameter so that the size can be retried
  276. // without copying any data. The application
  277. // can then call this function again to after it
  278. // has allocated a buffer of sufficient size to
  279. // handle the data.
  280. // Returns TRUE if successful. Otherwise, it returns FALSE.
  281. /////////////////////////////////////////////////////////////////
  282. virtual BOOL RecoverTransferData(ULONG *pulDataSize_ , void *pvData_ = NULL) = 0;
  283. /////////////////////////////////////////////////////////////////
  284. // Gets the partially received data from a failed transfer (download/manual transfer).
  285. //
  286. // Parameters:
  287. // *ulDataSize_ : Pointer to a ULONG that will receive
  288. // the size of the data available in bytes.
  289. // *pvData_ : Pointer to a buffer where the received data
  290. // will be copied. NULL can be passed to this
  291. // parameter so that the size can be retried
  292. // without copying any data. The application
  293. // can then call this function again to after it
  294. // has allocated a buffer of sufficient size to
  295. // handle the data.
  296. // Returns TRUE if successful. Otherwise, it returns FALSE.
  297. /////////////////////////////////////////////////////////////////
  298. virtual ANTFS_RETURN Authenticate(UCHAR ucAuthenticationType_, UCHAR *pucAuthenticationString_, UCHAR ucLength_, UCHAR *aucResponseBuffer_, UCHAR *pucResponseBufferSize_, ULONG ulResponseTimeout_) = 0;
  299. /////////////////////////////////////////////////////////////////
  300. // Request to pair with the connected remote device.
  301. // Parameters:
  302. // ucAuthenticationType_: The type of authentication to
  303. // execute on the remote device.
  304. // *pucAuthenticationString_: A string that may be used in
  305. // conjunction with the particular
  306. // authentication type in use (e.g. a
  307. // password or a friendly name.
  308. // ucLength_: The length of the authentication string,
  309. // including any '\n' terminator. This
  310. // parameter may be set to zero if an
  311. // authentication string is not required.
  312. // *pucResponseBuffer_: Pointer to the buffer where additional
  313. // data from the response will be saved. This will
  314. // include data such as passwords and friendly names.
  315. // This memory must be allocated by the application.
  316. // *pucResponseBufferSize_: Pointer to UCHAR varible that contains the
  317. // size of the buffer pointed to by pucResponseBuffer_.
  318. // After the response has be recived, the UCHAR variable
  319. // will be set to reflect the size of the new data received
  320. // in pucResponseBuffer_.
  321. // ulResponseTimeout_: Number of miliseconds to wait for a response after
  322. // the authenticate command is sent.
  323. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  324. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  325. // ANTFS_RETURN_BUSY if the library is busy with another request.
  326. // Operation:
  327. // Once the request is posted, the application must wait for the
  328. // response from the ANTFSHost object. Possible responses are:
  329. // ANTFS_HOST_RESPONSE_AUTHENTICATE_NA
  330. // ANTFS_HOST_RESPONSE_AUTHENTICATE_PASS
  331. // ANTFS_HOST_RESPONSE_AUTHENTICATE_REJECT
  332. // ANTFS_HOST_RESPONSE_AUTHENTICATE_FAIL
  333. // ANTFS_HOST_RESPONSE_CONNECTION_LOST
  334. // ANTFS_HOST_RESPONSE_SERIAL_FAIL
  335. // Upon receiving the ANTFS_HOST_RESPONSE_AUTHENTICATE_PASS, an
  336. // authentication string provided by the remoted device may be
  337. // available in the response buffer. This depends on the
  338. // authentication type used. The transport
  339. // layer connection is also only established after receiving
  340. // ANTFS_HOST_RESPONSE_AUTHENTICATE_PASS .
  341. /////////////////////////////////////////////////////////////////
  342. virtual ANTFS_RETURN Disconnect(USHORT usBlackoutTime_, UCHAR ucDisconnectType_ = 0, UCHAR ucTimeDuration_ = 0, UCHAR ucAppSpecificDuration_ = 0) = 0;
  343. /////////////////////////////////////////////////////////////////
  344. // Disconnect from a remote device. Optionally put that device
  345. // on a blackout list for a period of time. The application can
  346. // also request the remote device to become undiscoverable for a
  347. // specified time/application specific duration.
  348. // Parameters:
  349. // usBlackoutTime_: The number of seconds the device ID
  350. // should remain on the blackout list. If
  351. // set to zero (0), then the device will
  352. // not be put on the blackout list. If set
  353. // to MAX_USHORT (0xFFFF), the device will
  354. // remain on the blackout list until
  355. // explicitly removed, or until the blackout
  356. // list is reset.
  357. // ucDisconnectType_: Specifies whether the client should
  358. // return to LINK state or broadcast mode
  359. // (ANT-FS broadcast)
  360. // ucTimeDuration_: Time, in 30 seconds increments, the client
  361. // device will remain undiscoverable after
  362. // disconnect has been requested. Set to 0 to
  363. // disable.
  364. // ucAppSpecificDuration_: Application specific duration the client
  365. // shall remain undiscoverable after disconnection.
  366. // This field is left to the developer, or defined
  367. // in an ANT+ Device Profile. Set to 0 to disable.
  368. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  369. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  370. // ANTFS_RETURN_BUSY if the library is busy with another request.
  371. // Operation:
  372. // Once the request is posted, the application must wait for the
  373. // response from the ANTFSHost object. Possible responses are:
  374. // ANTFS_HOST_RESPONSE_DISCONNECT_PASS
  375. // ANTFS_HOST_RESPONSE_CONNECTION_LOST
  376. // ANTFS_HOST_RESPONSE_SERIAL_FAIL
  377. // The remote device will not show up in any search results for
  378. // the duration specified in usBlackoutTime_. This allows the
  379. // host to more easily find other devices in crowded
  380. // environments. The host can also request the remote device to
  381. // become undiscoverable, to more easily find other devices, however
  382. // not all client devices might implement this feature. Not all
  383. // client devices support a broadcast mode.
  384. /////////////////////////////////////////////////////////////////
  385. virtual BOOL Blackout(ULONG ulDeviceID_, USHORT usManufacturerID_, USHORT usDeviceType_, USHORT usBlackoutTime_) = 0;
  386. /////////////////////////////////////////////////////////////////
  387. // Put the device on a blackout list for a period of time.
  388. // Parameters:
  389. // ulDeviceID_: The device ID of a specific device.
  390. // usManufacturerID_: The specific manufacturer ID.
  391. // usDeviceType_: The specific device type.
  392. // usBlackoutTime_: The number of seconds the device ID
  393. // should remain on the blackout list. If
  394. // set to zero (0), then the device will
  395. // not be put on the blackout list. If set
  396. // to MAX_USHORT (0xFFFF), the device will
  397. // remain on the blackout list until
  398. // explicitly removed, or until the blackout
  399. // list is reset.
  400. // Returns TRUE if successful. Otherwise, it returns FALSE.
  401. // A wildcard parameter (0) is not allowed in any of the device
  402. // ID parameters and will result in returning FALSE.
  403. // Operation:
  404. // The remote device will not show up in any search results for
  405. // the duration specified in usBlackoutTime_. This allows the
  406. // host to more easily find other devices in crowded
  407. // environments.
  408. /////////////////////////////////////////////////////////////////
  409. virtual BOOL RemoveBlackout(ULONG ulDeviceID_, USHORT usManufacturerID_, USHORT usDeviceType_) = 0;
  410. /////////////////////////////////////////////////////////////////
  411. // Remove the device from the blackout list.
  412. // Parameters:
  413. // ulDeviceID_: The device ID of a specific device.
  414. // usManufacturerID_: The specific manufacturer ID.
  415. // usDeviceType_: The specific device type.
  416. // Returns TRUE if successful. Returns FALSE if the device is
  417. // not found in the blackout list. A wildcard parameter (0) is
  418. // not allowed in any of the device ID parameters and will result
  419. // in returning FALSE.
  420. /////////////////////////////////////////////////////////////////
  421. virtual void ClearBlackoutList(void) = 0;
  422. /////////////////////////////////////////////////////////////////
  423. // Clears the blackout list.
  424. /////////////////////////////////////////////////////////////////
  425. virtual ANTFS_RETURN Download(USHORT usFileIndex_, ULONG ulDataOffset_, ULONG ulMaxDataLength_, ULONG ulMaxBlockSize_ = 0) = 0;
  426. /////////////////////////////////////////////////////////////////
  427. // Request a download of a file from the authenticated device.
  428. // Parameters:
  429. // usFileIndex_: The file number to be downloaded. Some
  430. // file numbers are reserved for special
  431. // purposes, such as the device directory
  432. // (0). Consult the ANT_FS specification
  433. // and any docs for specific device types.
  434. // ulDataOffset_: The byte offset from where to begin
  435. // transferring the data.
  436. // ulMaxDataLength_: ULONG varible that contains the maximum
  437. // number of bytes to download. Set to 0 if
  438. // if the host does not wish to limit the
  439. // size of the download.
  440. // ulMaxBlockSize_: Maximum number of bytes that the host
  441. // wishes to download in a single block.
  442. // Set to zero to disable.
  443. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  444. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  445. // ANTFS_RETURN_BUSY if the library is busy with another request.
  446. // Operation:
  447. // Once the request is posted, the application must wait for the
  448. // response from the ANTFSHost object. Possible responses are:
  449. // ANTFS_HOST_RESPONSE_DOWNLOAD_PASS
  450. // ANTFS_HOST_RESPONSE_DOWNLOAD_REJECT
  451. // ANTFS_HOST_RESPONSE_DOWNLOAD_FAIL
  452. // ANTFS_HOST_RESPONSE_CONNECTION_LOST
  453. // ANTFS_HOST_RESPONSE_SERIAL_FAIL
  454. // Upon receiving ANTFS_HOST_RESPONSE_DOWNLOAD_PASS the downloaed data
  455. // will be available in the transfer buffer. See GetTransferData().
  456. /////////////////////////////////////////////////////////////////
  457. virtual ANTFS_RETURN Upload(USHORT usFileIndex_, ULONG ulDataOffset_, ULONG ulDataLength_, void *pvData_, BOOL bForceOffset_ = TRUE, ULONG ulMaxBlockSize_ = 0) = 0;
  458. /////////////////////////////////////////////////////////////////
  459. // Request an upload of a file to the authenticated device.
  460. // Parameters:
  461. // usFileIndex_: The file number to be uploaded. Some
  462. // file numbers are reserved for special
  463. // purposes, such as the device directory
  464. // (0). Consult the ANT_FS specification
  465. // and any docs for specific device types.
  466. // ulDataOffset_: The byte offset from where to begin
  467. // transferring the data.
  468. // ulDataLength_: The byte length of data to be uploaded
  469. // to the remote device.
  470. // Return value:
  471. // *pvData_: Pointer to the location where the data
  472. // to be uploaded is stored.
  473. // bForceOffset_: Set to TRUE (default) to enforce the
  474. // provided byte data offset. Set to FALSE
  475. // to continue a transfer, indicating that
  476. // the host will continue the upload at the
  477. // last data offset specified by the client
  478. // in the Upload Response.
  479. // ulMaxBlockSize_: Maximum block size that the host can send
  480. // in a single block of data. Set to zero
  481. // to disable
  482. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  483. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  484. // ANTFS_RETURN_BUSY if the library is busy with another request.
  485. // Operation:
  486. // Once the request is posted, the application must wait for the
  487. // response from the ANTFSHost object. Possible responses are:
  488. // ANTFS_HOST_RESPONSE_UPLOAD_PASS
  489. // ANTFS_HOST_RESPONSE_UPLOAD_REJECT
  490. // ANTFS_HOST_RESPONSE_UPLOAD_FAIL
  491. // ANTFS_HOST_RESPONSE_CONNECTION_LOST
  492. // ANTFS_HOST_RESPONSE_SERIAL_FAIL
  493. /////////////////////////////////////////////////////////////////
  494. virtual ANTFS_RETURN ManualTransfer(USHORT usFileIndex_, ULONG ulDataOffset_, ULONG ulDataLength_, void *pvData_) = 0;
  495. /////////////////////////////////////////////////////////////////
  496. // Send data directly to the device without requesting first.
  497. // This is especially useful for communicating small pieces of
  498. // data to the device. Another use is the implementation of a
  499. // higher-level communication protocol. Care must be taken to
  500. // ensure the device can handle the amount of data being sent
  501. // using this method.
  502. // usFileIndex_: The file number to be uploaded. Some
  503. // file numbers are reserved for special
  504. // purposes, such as the device directory
  505. // (0). Consult the ANT_FS specification
  506. // and any docs for specific device types.
  507. // ulDataOffset_: The byte offset from where to begin
  508. // transferring the data. Note that this
  509. // value will always get rounded up to the
  510. // next higher multiple of 8. Under normal
  511. // use, this parameter should always be set
  512. // to zero, and the only time it would be
  513. // non-zero is for retrying ManualTransfer()
  514. // from a known offset.
  515. // ulDataLength_: The byte length of data to be sent to
  516. // the remote device.
  517. // *pvData_: The Pointer to a buffer where the
  518. // data to be sent is stored.
  519. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  520. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  521. // ANTFS_RETURN_BUSY if the library is busy with another request.
  522. // Operation:
  523. // Once the request is posted, the application must wait for the
  524. // response from the ANTFSHost object. Possible responses are:
  525. // ANTFS_HOST_RESPONSE_MANUAL_TRANSFER_PASS
  526. // ANTFS_HOST_RESPONSE_MANUAL_TRANSFER_TRANSMIT_FAIL
  527. // ANTFS_HOST_RESPONSE_MANUAL_TRANSFER_RESPONSE_FAIL
  528. // ANTFS_HOST_RESPONSE_CONNECTION_LOST
  529. // ANTFS_HOST_RESPONSE_SERIAL_FAIL
  530. // Upon receiving ANTFS_HOST_RESPONSE_MANUAL_TRANSFER_PASS the downloaed data
  531. // will be available in the transfer buffer. See GetTransferData().
  532. /////////////////////////////////////////////////////////////////
  533. virtual ANTFS_RETURN EraseData(USHORT usFileIndex_) = 0;
  534. /////////////////////////////////////////////////////////////////
  535. // Request the erasure of a file on the authenticated remote
  536. // device.
  537. // Parameters:
  538. // usFileIndex_: The file number of the file to be erased.
  539. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  540. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  541. // ANTFS_RETURN_BUSY if the library is busy with another request.
  542. // Operation:
  543. // Once the request is posted, the application must wait for the
  544. // response from the ANTFSHost object. Possible responses are:
  545. // ANTFS_HOST_RESPONSE_ERASE_PASS
  546. // ANTFS_HOST_RESPONSE_ERASE_FAIL
  547. // ANTFS_HOST_RESPONSE_CONNECTION_LOST
  548. // ANTFS_HOST_RESPONSE_SERIAL_FAIL
  549. /////////////////////////////////////////////////////////////////
  550. virtual BOOL EnablePing(BOOL bEnable_) = 0;
  551. /////////////////////////////////////////////////////////////////
  552. // Enables ping message to be sent to the remote device periodically.
  553. // This can be used to keep the remote device from timing out during
  554. // operations that wait for user input (i.e. pairing).
  555. // Parameters:
  556. // bEnable_: Periodic ping enable.
  557. // Returns TRUE if successful. Otherwise, it returns FALSE.
  558. /////////////////////////////////////////////////////////////////
  559. };
  560. #endif // !defined(ANTFS_HOST_INTERFACE_H)