antfs_client_channel.hpp 40 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780
  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_CLIENT_CHANNEL_HPP)
  9. #define ANTFS_CLIENT_CHANNEL_HPP
  10. #include "types.h"
  11. #include "dsi_thread.h"
  12. #include "dsi_timer.hpp"
  13. #include "dsi_framer_ant.hpp"
  14. #include "dsi_debug.hpp"
  15. #include "dsi_response_queue.hpp"
  16. #include "dsi_ant_message_processor.hpp"
  17. #include "antfs_client_interface.hpp"
  18. //////////////////////////////////////////////////////////////////////////////////
  19. // Public Definitions
  20. //////////////////////////////////////////////////////////////////////////////////
  21. typedef struct
  22. {
  23. char acFriendlyName[FRIENDLY_NAME_MAX_LENGTH];
  24. BOOL bNameSet;
  25. UCHAR ucIndex;
  26. UCHAR ucSize;
  27. } ANTFS_FRIENDLY_NAME;
  28. /////////////////////////////////////////////////////////////////
  29. // This class implements the ANT-FS Client specification.
  30. // It is intended to be used together with another class that manages
  31. // the connection to an ANT USB stick (e.g. DSIANTDevice or
  32. // .NET ANT_Device).
  33. /////////////////////////////////////////////////////////////////
  34. class ANTFSClientChannel : public ANTFSClientInterface, public DSIANTMessageProcessor
  35. {
  36. private:
  37. //////////////////////////////////////////////////////////////////////////////////
  38. // Private Definitions
  39. //////////////////////////////////////////////////////////////////////////////////
  40. enum ENUM_ANTFS_REQUEST
  41. {
  42. ANTFS_REQUEST_NONE = 0,
  43. ANTFS_REQUEST_INIT, // Init()
  44. ANTFS_REQUEST_OPEN_BEACON, // OpenBeacon()
  45. ANTFS_REQUEST_CLOSE_BEACON, // CloseBeacon()
  46. ANTFS_REQUEST_CONNECT, // From Host: Switch to Authenticate
  47. ANTFS_REQUEST_DISCONNECT, // From Host: End session
  48. ANTFS_REQUEST_PING, // From Host: Keep session alive
  49. ANTFS_REQUEST_AUTHENTICATE, // From Host: Send authentication Response
  50. ANTFS_REQUEST_PAIR, // From Host: Send pairing request to application
  51. ANTFS_REQUEST_CHANGE_LINK, // From Host: Switch frequency/period
  52. ANTFS_REQUEST_DOWNLOAD, // From Host: Download requested
  53. ANTFS_REQUEST_DOWNLOAD_RESPONSE, // SendDownloadResponse();
  54. ANTFS_REQUEST_UPLOAD, // From Host: Upload requested
  55. ANTFS_REQUEST_UPLOAD_RESPONSE, // SendUploadResponse()
  56. ANTFS_REQUEST_UPLOAD_COMPLETE, // SendUploadComplete()
  57. ANTFS_REQUEST_ERASE, // From Host: Erase request
  58. ANTFS_REQUEST_ERASE_RESPONSE, // SendEraseResponse()
  59. ANTFS_REQUEST_CONNECTION_LOST, // Internal, keep these at the end of the list order is important
  60. ANTFS_REQUEST_HANDLE_SERIAL_ERROR, // Internal
  61. ANTFS_REQUEST_SERIAL_ERROR_HANDLED // Internal
  62. };
  63. enum RETURN_STATUS
  64. {
  65. RETURN_FAIL = 0,
  66. RETURN_PASS,
  67. RETURN_STOP,
  68. RETURN_REJECT,
  69. RETURN_NA,
  70. RETURN_SERIAL_ERROR
  71. };
  72. //////////////////////////////////////////////////////////////////////////////////
  73. // Private Variables
  74. //////////////////////////////////////////////////////////////////////////////////
  75. DSIResponseQueue<ANTFS_CLIENT_RESPONSE> clResponseQueue;
  76. BOOL bInitFailed;
  77. UCHAR aucResponseBuf[MESG_MAX_SIZE_VALUE];
  78. UCHAR aucRxBuf[MESG_MAX_SIZE_VALUE];
  79. DSI_THREAD_ID hANTFSThread; // Handle for the ANTFS thread.
  80. DSI_MUTEX stMutexResponseQueue; // Mutex used with the response queue
  81. DSI_MUTEX stMutexCriticalSection; // Mutex used with the wait condition
  82. DSI_MUTEX stMutexPairingTimeout; // Mutex used with the pairing timeouts
  83. DSI_CONDITION_VAR stCondANTFSThreadExit; // Event to signal the ANTFS thread has ended
  84. DSI_CONDITION_VAR stCondRequest; // Event to signal there is a new request
  85. DSI_CONDITION_VAR stCondRxEvent; // Event to signal there is a new Rx message or failure
  86. DSI_CONDITION_VAR stCondWaitForResponse; // Event to signal there is a new response to the application
  87. DSITimer *pclTimer;
  88. volatile BOOL bTimerRunning;
  89. volatile BOOL bANTFSThreadRunning;
  90. volatile BOOL bKillThread;
  91. volatile BOOL bCancel; // Internal cancel parameter to use if not configured
  92. volatile BOOL *pbCancel;
  93. DSIFramerANT *pclANT;
  94. // ANT Channel parameters
  95. UCHAR ucNetworkNumber;
  96. //UCHAR ucChannelNumber;
  97. USHORT usRadioChannelID; // ANT Channel Device ID
  98. UCHAR ucTheDeviceType;
  99. UCHAR ucTheTransmissionType;
  100. USHORT usTheMessagePeriod;
  101. UCHAR aucTheNetworkkey[8];
  102. UCHAR ucLinkTxPower;
  103. UCHAR ucSessionTxPower;
  104. BOOL bCustomTxPower;
  105. // Bursting
  106. volatile ULONG ulPacketCount;
  107. volatile BOOL bTxError;
  108. volatile BOOL bRxError;
  109. volatile BOOL bReceivedBurst;
  110. volatile BOOL bReceivedCommand;
  111. volatile BOOL bNewRxEvent;
  112. // Beacon parameters
  113. ANTFS_CLIENT_PARAMS stInitParams; // Initial parameters
  114. UCHAR aucFriendlyName[FRIENDLY_NAME_MAX_LENGTH]; // Cache application defined friendly name
  115. UCHAR aucPassKey[PASSWORD_MAX_LENGTH]; // Cache application defined passkey
  116. UCHAR ucPassKeySize; // PassKey length
  117. UCHAR ucFriendlyNameSize; // Friendly name length
  118. UCHAR ucActiveBeaconFrequency; // Active radio frequency for the beacon
  119. UCHAR ucActiveBeaconStatus1; // Beacon Status 1 byte
  120. UCHAR aucBeacon[8]; // Beacon buffer
  121. USHORT usBeaconChannelPeriod; // If custom period (not defined by ANT-FS)
  122. // ANT-FS Broadcast
  123. BOOL bReturnToBroadcast; // Default action when closing the beacon
  124. // Link state
  125. ULONG ulHostSerialNumber;
  126. // Authentication state
  127. ANTFS_FRIENDLY_NAME stHostFriendlyName; // Host Friendly Name
  128. UCHAR ucPassKeyIndex; // Current location of auth string Tx block
  129. UCHAR ucAuthCommandType; // Authentication command type in progress
  130. BOOL bAcceptRequest; // Accept/reject authentication request
  131. // Pairing
  132. UCHAR ucPairingTimeout;
  133. volatile BOOL bTimeoutEvent;
  134. // Disconnect
  135. ANTFS_DISCONNECT_PARAMS stHostDisconnectParams; // Parameters received from the hsot on a disconnect request
  136. // Transport state
  137. ANTFS_REQUEST_PARAMS stHostRequestParams; // Parameters received from the host on a file transfer request
  138. UCHAR ucRequestResponse; // Response from the application to the request
  139. // Data transfer
  140. USHORT usTransferDataFileIndex; // Index of current file being transferred
  141. volatile ULONG ulTransferFileSize; // File size of current transfer, in bytes
  142. volatile ULONG ulTransferBurstIndex; // Current location within the burst block, in bytes
  143. volatile ULONG ulTransferBytesRemaining; // Total remaining data length of the current block, in bytes
  144. volatile ULONG ulTransferMaxIndex; // Upper limit of the current transmitted burst block, in bytes
  145. volatile ULONG ulTransferBlockSize; // Maximum block size, limited by client device
  146. volatile USHORT usTransferCrc; // Data CRC
  147. volatile USHORT usSavedTransferCrc; // Used in case upload isn't complete
  148. volatile ULONG ulDownloadProgress; // Current download progress (number of bytes transferred)
  149. volatile ULONG ulTransferBlockOffset; // Offset, in bytes, of the data block provided by the application
  150. volatile ULONG ulTransferBufferSize;
  151. UCHAR *pucDownloadData; // Buffer with data to download
  152. UCHAR *pucTransferBufferDynamic; // Dynamic buffer for uploads
  153. volatile ENUM_ANTFS_REQUEST eANTFSRequest;
  154. volatile ANTFS_CLIENT_STATE eANTFSState;
  155. volatile UCHAR ucLinkCommandInProgress;
  156. //////////////////////////////////////////////////////////////////////////////////
  157. // Private Function Prototypes
  158. //////////////////////////////////////////////////////////////////////////////////
  159. void ANTFSThread(void);
  160. static DSI_THREAD_RETURN ANTFSThreadStart(void *pvParameter_);
  161. void TimerCallback(void);
  162. static DSI_THREAD_RETURN TimerStart(void *pvParameter_);
  163. void SetDefaultBeacon(void);
  164. void ResetClientState(void);
  165. BOOL ReInitDevice(void);
  166. void HandleSerialError(void);
  167. BOOL FilterANTMessages(ANT_MESSAGE* pstMessage_, UCHAR ucANTChannel_);
  168. BOOL ANTProtocolEventProcess(UCHAR ucChannel_, UCHAR ucMessageCode_);
  169. BOOL ANTChannelEventProcess(UCHAR ucChannel_, UCHAR ucMessageCode_);
  170. void AddResponse(ANTFS_CLIENT_RESPONSE eResponse_);
  171. void LoadBeacon(void);
  172. RETURN_STATUS AttemptOpenBeacon(void);
  173. RETURN_STATUS AttemptCloseBeacon(void);
  174. RETURN_STATUS AttemptAuthenticateResponse(void);
  175. RETURN_STATUS AttemptEraseResponse(void);
  176. RETURN_STATUS AttemptDownloadResponse(void);
  177. RETURN_STATUS AttemptUploadResponse(void);
  178. RETURN_STATUS AttemptUploadDataResponse(void);
  179. void DecodeLinkCommand(UCHAR *pucLinkCommand_);
  180. void DecodeAuthenticateCommand(UCHAR ucControlByte_, UCHAR *pucAuthCommand_);
  181. void DecodeTransportCommand(UCHAR ucControlByte_, UCHAR *pucTransCommand_);
  182. void UploadInputData(UCHAR ucControlByte_, UCHAR* pucMesg_);
  183. RETURN_STATUS SwitchToLink(void);
  184. RETURN_STATUS SwitchToAuthenticate(void);
  185. RETURN_STATUS SwitchToTransport(void);
  186. RETURN_STATUS SwitchLinkParameters(void);
  187. void SetANTChannelPeriod(UCHAR ucLinkPeriod_);
  188. public:
  189. //////////////////////////////////////////////////////////////////////////////////
  190. // Public Function Prototypes
  191. //////////////////////////////////////////////////////////////////////////////////
  192. ANTFSClientChannel();
  193. ~ANTFSClientChannel();
  194. BOOL Init(DSIFramerANT* pclANT_, UCHAR ucChannel_);
  195. /////////////////////////////////////////////////////////////////
  196. // Begins to initialize the ANTFSClientChannel object.
  197. // Returns TRUE if successful. Otherwise, it returns FALSE.
  198. // Parameters:
  199. // *pclANT_: Pointer to a DSIFramerANT object.
  200. // ucChannel_: Channel number to use for the ANT-FS host
  201. // Operation:
  202. // This function is used from a class managing the connection
  203. // to ANT (e.g. DSIANTDevice or .NET ANT_Device), to
  204. // initialize the ANTFSClientChannel object. It is not possible
  205. // to change the channel number once ANT-FS is running.
  206. // The function returns immediately, and the ANTFSHostChannel object
  207. // will send a response of ANTFS_HOST_RESPONSE_INIT_PASS.
  208. // IT IS NOT NECESSARY TO CALL THIS FUNCTION DIRECTLY FROM USER APPLICATIONS.
  209. /////////////////////////////////////////////////////////////////
  210. void Close(void);
  211. /////////////////////////////////////////////////////////////////
  212. // Stops any pending actions, closes all threads and cleans
  213. // up any dynamic memory being used by the library.
  214. // Operation:
  215. // This function is used from a class managing the connection
  216. // to ANT (e.g. DSIANTDevice or .NET ANT_Device), to
  217. // clean up any resources in use by the ANT-FS host.
  218. // IT IS NOT NECESSARY TO CALL THIS FUNCTION DIRECTLY FROM USER APPLICATIONS.
  219. /////////////////////////////////////////////////////////////////
  220. void ProcessMessage(ANT_MESSAGE* pstMessage_, USHORT usMesgSize_);
  221. /////////////////////////////////////////////////////////////////
  222. // Processes incoming ANT messages as per the ANT-FS Technology
  223. // Specification
  224. // Parameters:
  225. // pstMessage_: Pointer to an ANT message structure
  226. // usMesgSize_: ANT message size
  227. // Operation:
  228. // This function is used from a class managing the connection
  229. // to ANT (e.g. DSIANTDevice or .NET ANT_Device).
  230. // IT IS NOT NECESSARY TO CALL THIS FUNCTION DIRECTLY FROM USER APPLICATIONS.
  231. /////////////////////////////////////////////////////////////////
  232. void ProcessDeviceNotification(ANT_DEVICE_NOTIFICATION eCode_, void* pvParameter_);
  233. /////////////////////////////////////////////////////////////////
  234. // Processes device level notifications
  235. // Parameters:
  236. // eCode_: Device notification event code
  237. // pvParameter_: Pointer to struct defining specific parameters related
  238. // to the event code
  239. // Operation:
  240. // This function is used from a class managing the connection
  241. // to ANT (e.g. DSIANTDevice or .NET ANT_Device).
  242. // IT IS NOT NECESSARY TO CALL THIS FUNCTION DIRECTLY FROM USER APPLICATIONS.
  243. /////////////////////////////////////////////////////////////////
  244. void Cancel(void);
  245. /////////////////////////////////////////////////////////////////
  246. // Cancels any pending actions and returns the library to the
  247. // appropriate ANTFS layer if possible. ie if the library was
  248. // executing a download command in the transport layer, the
  249. // library would be returned to ANTFS_CLIENT_STATE_TRANSPORT after
  250. // execution of this function.
  251. /////////////////////////////////////////////////////////////////
  252. // TODO: Serial number is configured within InitParams. Should it be a
  253. // separate SetSerialNumber function for consistency with the host, or
  254. // should the host be configured with a struct as in this function?
  255. ANTFS_RETURN ConfigureClientParameters(ANTFS_CLIENT_PARAMS* pstInitParams_);
  256. /////////////////////////////////////////////////////////////////
  257. // Set up the ANTFS Client configuration parameters.
  258. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  259. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  260. // ANTFS_RETURN_BUSY if the library is busy with another request.
  261. // Parameters:
  262. // *pstInitParams_: A pointer to an
  263. // ANTFS_PARAMS structure that defines the
  264. // configuration parameters of the client
  265. // device
  266. // Operation:
  267. // This function can only be used before the beacon is open;
  268. // Changes are only applied when calling OpenBeacon().
  269. // Certain parameters can be changed at any time, see
  270. // SetPairingEnabled
  271. // SetUploadEnabled
  272. // SetDataAvailable
  273. // SetBeaconTimeout
  274. // SetPairingTimeout
  275. // If the client is not configured prior to opening the
  276. // beacon, the default ANT-FS PC beacon configuration is used.
  277. /////////////////////////////////////////////////////////////////
  278. ANTFS_RETURN SetPairingEnabled(BOOL bEnable_);
  279. /////////////////////////////////////////////////////////////////
  280. // Enable handling of pairing authentication requests, and indicate
  281. // so in the beacon.
  282. // Parameters:
  283. // bEnable_: Set to TRUE to enable pairing and FALSE
  284. // to disable.
  285. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  286. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  287. // ANTFS_RETURN_BUSY if the library is busy with another request.
  288. // Operation:
  289. // This function can be used at any time, except while handling
  290. // an authentication request
  291. /////////////////////////////////////////////////////////////////
  292. ANTFS_RETURN SetUploadEnabled(BOOL bEnable_);
  293. /////////////////////////////////////////////////////////////////
  294. // Enable uploads, indicating so in the beacon.
  295. // Parameters:
  296. // bEnable_: Set to TRUE to enable pairing and FALSE
  297. // to disable.
  298. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  299. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  300. // ANTFS_RETURN_BUSY if the library is busy with another request.
  301. // Operation:
  302. // This function can be used at any time, except while handling
  303. // a transport request (i.e. during an upload)
  304. /////////////////////////////////////////////////////////////////
  305. ANTFS_RETURN SetDataAvailable(BOOL bDataAvailable_);
  306. /////////////////////////////////////////////////////////////////
  307. // Indicate in the beacon whether data is available for download.
  308. // Parameters:
  309. // bDataAvailable_: Set to TRUE if data is available and
  310. // FALSE if not.
  311. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  312. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  313. // ANTFS_RETURN_BUSY if the library is busy with another request.
  314. // Operation:
  315. // This function can be used at any time, except while handling
  316. // a transport request (i.e. during a download)
  317. /////////////////////////////////////////////////////////////////
  318. // TODO: SetState (Status1 byte, consistent with integrated FS interface)?
  319. void SetBeaconTimeout(UCHAR ucTimeout_);
  320. /////////////////////////////////////////////////////////////////
  321. // Set up the time the client will wait without receiving any
  322. // commands from the host before dropping back to the link state
  323. // Parameters:
  324. // ucTimeout_: Timeout, in seconds. Set to 0xFF to
  325. // disable (infinite timeout).
  326. // Zero is not an allowed value.
  327. /////////////////////////////////////////////////////////////////
  328. void SetPairingTimeout(UCHAR ucTimeout_);
  329. /////////////////////////////////////////////////////////////////
  330. // Set up the time the client will wait without receiving any
  331. // response from the application to a pairing request before
  332. // rejecting it
  333. // Parameters:
  334. // ucTimeout_: Timeout, in seconds. Set to 0xFF to
  335. // disable (infinite timeout).
  336. // Zero is not an allowed value.
  337. /////////////////////////////////////////////////////////////////
  338. ANTFS_RETURN SetFriendlyName(UCHAR* pucFriendlyName_, UCHAR ucFriendlyNameSize_);
  339. /////////////////////////////////////////////////////////////////
  340. // Set up a friendly name for the ANT-FS client
  341. // Parameters:
  342. // *pucFriendlyName: A pointer to a character string
  343. // containing the friendly name of the client.
  344. // Set to NULL to disable
  345. // ucFriendlyNameSize: Size of the friendly name string (max 255)
  346. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  347. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  348. // ANTFS_RETURN_BUSY if the library is busy with another request.
  349. // Operation:
  350. // This function can be used at any time, except while handling
  351. // an authentication request.
  352. // No friendly name will be sent with authentication responses
  353. // unless configured with this command.
  354. // The friendly name is cached by the client library.
  355. /////////////////////////////////////////////////////////////////
  356. ANTFS_RETURN SetPassKey(UCHAR* pucPassKey_, UCHAR ucPassKeySize_);
  357. /////////////////////////////////////////////////////////////////
  358. // Set up the pass key for the client to establish authenticated
  359. // sessions with a host device
  360. // Parameters:
  361. // *pucPassKey: Array containing the pass key
  362. // Set to NULL to disable
  363. // ucPassKeySize: Size of the passkey (max 255)
  364. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  365. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  366. // ANTFS_RETURN_BUSY if the library is busy with another request.
  367. // Operation:
  368. // This function can be used at any time, except while handling
  369. // an authentication request.
  370. // PassKey authentication is disabled by default, unless
  371. // this command is called to configure a key.
  372. // The passkey is cached by the client library.
  373. /////////////////////////////////////////////////////////////////
  374. void SetChannelID(UCHAR ucDeviceType_, UCHAR ucTransmissionType_);
  375. /////////////////////////////////////////////////////////////////
  376. // Set up the ANT Channel ID for the ANT-FS Client
  377. // Parameters:
  378. // ucDeviceType_: ANT Channel Device Type
  379. // ucTransmissionType_: ANT Channel Transmission Type
  380. // Operation:
  381. // Configuration changes are applied when the beacon is opened
  382. /////////////////////////////////////////////////////////////////
  383. void SetChannelPeriod(USHORT usChannelPeriod_);
  384. /////////////////////////////////////////////////////////////////
  385. // Set up a custom ANT channel period
  386. // Parameters:
  387. // usChannelPeriod_: Message count, in seconds * 32768.
  388. // For example, for 4Hz, set to 8192.
  389. // Operation:
  390. // Use this function if using ANT-FS broadcast and configuring a
  391. // beacon period not defined in the ANT-FS Technology Specification
  392. // When using this option, set the Link Period beacon parameter to
  393. // BEACON_PERIOD_KEEP. This is the channel period the client will
  394. // use when in LINK state or when it returns to broadcast.
  395. /////////////////////////////////////////////////////////////////
  396. void SetNetworkKey(UCHAR ucNetwork_, UCHAR ucNetworkKey[]);
  397. /////////////////////////////////////////////////////////////////
  398. // Set up the network key to use with the ANT-FS Client
  399. // Parameters:
  400. // ucNetwork_: Network number
  401. // ucNetorkKey_: Array containing the 8-byte network key
  402. // Operation:
  403. // Configuration changes are applied when the beacon is opened
  404. /////////////////////////////////////////////////////////////////
  405. void SetTxPower(UCHAR ucPairingLv_, UCHAR ucConnectedLv_);
  406. /////////////////////////////////////////////////////////////////
  407. // Set up the transmit power for the ANT-FS Channel.
  408. // Parameters:
  409. // ucPairingLv_: Power level to use while beaconing (link)
  410. // ucConnectedLv_: Power level to use during a session
  411. // Operation:
  412. // This command can be used to facilitate pairing when
  413. // proximity search is used in the host device.
  414. // If the ANT part does not support setting the transmit power
  415. // on a per channel basis, it is set for all channels
  416. // Configuration changes are applied when the client switches
  417. // to the link and authentication states.
  418. /////////////////////////////////////////////////////////////////
  419. ANTFS_RETURN OpenBeacon(void);
  420. /////////////////////////////////////////////////////////////////
  421. // Begins the channel configuration to transmit the ANT-FS beacon
  422. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  423. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  424. // ANTFS_RETURN_BUSY if the library is busy with another request.
  425. // Operation:
  426. // This function will configure the beacon and start broadcasting.
  427. // If the channel is already open (i.e. broadcast mode), only the
  428. // contents of the beacon will change, not the channel configuration.
  429. // Once the channel is successfully configured and opened,
  430. // a response of ANTFS_CLIENT_RESPONSE_BEACON_OPEN will be sent.
  431. /////////////////////////////////////////////////////////////////
  432. ANTFS_RETURN CloseBeacon(BOOL bReturnToBroadcast_ = FALSE);
  433. /////////////////////////////////////////////////////////////////
  434. // Closes the ANT-FS beacon.
  435. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  436. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  437. // ANTFS_RETURN_BUSY if the library is busy with another request.
  438. // Parameters:
  439. // bReturnToBroadcast_: If TRUE, the channel will remain
  440. // open, and the application can continue
  441. // to process messages. If FALSE,
  442. // the channel will be closed.
  443. // Operation:
  444. // Once the channel is successfully closed, a response of
  445. // ANTFS_CLIENT_RESPONSE_BEACON_CLOSED will be sent,
  446. // and the ANTFSClient will be in the ANTFS_STATE_IDLE state.
  447. // If the ReturnToBroadcast parameter is not used, the default
  448. // behavior will be to close the channel and stop broadcasting.
  449. /////////////////////////////////////////////////////////////////
  450. BOOL GetEnabled(void);
  451. /////////////////////////////////////////////////////////////////
  452. // Returns the current status of ANT-FS message processing
  453. // Returns TRUE if ANT-FS is enabled. Otherwise, it returns FALSE.
  454. // Operation:
  455. // This function is used from a class managing the connection
  456. // to ANT (e.g. DSIANTDevice or .NET ANT_Device).
  457. // IT IS NOT NECESSARY TO CALL THIS FUNCTION DIRECTLY FROM USER APPLICATIONS.
  458. /////////////////////////////////////////////////////////////////
  459. ANTFS_CLIENT_STATE GetStatus(void);
  460. /////////////////////////////////////////////////////////////////
  461. // Returns the current library status.
  462. /////////////////////////////////////////////////////////////////
  463. BOOL GetHostName(UCHAR *aucHostFriendlyName_, UCHAR *pucBufferSize_);
  464. /////////////////////////////////////////////////////////////////
  465. // Copies at most ucBufferSize_ characters from the host's
  466. // friendly name string (for the most recent session) into the
  467. // supplied pucHostFriendlyName_ buffer.
  468. // Parameters:
  469. // *aucFriendlyName_: A pointer to a buffer where the remote
  470. // device friendly name will be copied.
  471. // *pucBufferSize_: Pointer to a UCHAR variable that should contain the
  472. // maximum size of the buffer pointed to by
  473. // aucHostFriendlyName_.
  474. // After the function returns, the UCHAR variable
  475. // will be set to reflect the size of the friendly
  476. // name string that has been copied to the buffer.
  477. // Returns TRUE if successful. Otherwise, it returns FALSE.
  478. // Operation:
  479. // If the host's friendly name string has fewer than ucBufferSize_
  480. // characters, the *aucFriendlyName_ buffer will be padded with
  481. // zeroes.
  482. /////////////////////////////////////////////////////////////////
  483. BOOL GetRequestParameters(ANTFS_REQUEST_PARAMS* pstRequestParams_);
  484. /////////////////////////////////////////////////////////////////
  485. // Gets the full parameters for a download, upload or erase request
  486. // received from the host.
  487. //
  488. // Parameters:
  489. // *pstRequestParams_: Pointer to an ANTFS_REQUEST_PARAMS
  490. // structure that will receive the details
  491. // of the download, upload or erase request.
  492. // Returns TRUE if successful. Otherwise, it returns FALSE.
  493. // Operation:
  494. // This function makes available all of the parameters received
  495. // from the host when requesting a data transfer. These
  496. // parameters are available for information purposes; the client
  497. // application only needs to process the index to handle the
  498. // request.
  499. // This information is valid while a download, upload or erase
  500. // request is in progress.
  501. /////////////////////////////////////////////////////////////////
  502. BOOL GetRequestedFileIndex(USHORT *pusIndex_);
  503. /////////////////////////////////////////////////////////////////
  504. // Gets the index requested for a download, upload or erase request
  505. // Parameters:
  506. // *pulByteProgress_: Pointer to a USHORT that will receive
  507. // the current fle index requested
  508. // Returns TRUE if successful. Otherwise, it returns FALSE.
  509. // Operation:
  510. // This information is valid while a download, upload or erase
  511. // request is in progress.
  512. /////////////////////////////////////////////////////////////////
  513. BOOL GetDownloadStatus(ULONG *pulByteProgress_, ULONG *pulTotalLength_);
  514. /////////////////////////////////////////////////////////////////
  515. // Gets the transfer progress of a pending or a complete
  516. // download.
  517. // Parameters:
  518. // *pulByteProgress_: Pointer to a ULONG that will receive
  519. // the current byte progress of a pending or
  520. // complete download.
  521. // *pulTotalLength_: Pointer to a ULONG that will receive the
  522. // total expected length of the download.
  523. // Returns TRUE if successful. Otherwise, it returns FALSE.
  524. // Operation:
  525. // A data download occurs when information is requested from a
  526. // remote device. This function may be called at any point
  527. // during a download as a progress indicator. After the transfer
  528. // is complete, this information is valid until another request
  529. // for a data transfer is made.
  530. /////////////////////////////////////////////////////////////////
  531. BOOL GetUploadStatus(ULONG *pulByteProgress_, ULONG *pulTotalLength_);
  532. /////////////////////////////////////////////////////////////////
  533. // Gets the transfer progress of a pending or a complete
  534. // upload.
  535. // Parameters:
  536. // *pulByteProgress_: Pointer to a ULONG that will receive
  537. // the current byte progress of a pending or
  538. // complete upload.
  539. // *pulTotalLength_: Pointer to a ULONG that will receive the
  540. // total expected length of the upload.
  541. // Returns TRUE if successful. Otherwise, it returns FALSE.
  542. // Operation:
  543. // A data upload occurs when information is sent to a
  544. // remote device. This function may be called at any point
  545. // during an upload as a progress indicator. After the transfer
  546. // is complete, this information is valid until another request
  547. // for a data transfer is made.
  548. /////////////////////////////////////////////////////////////////
  549. BOOL GetTransferData(ULONG *pulOffset_, ULONG *pulDataSize_ , void *pvData_ = NULL);
  550. /////////////////////////////////////////////////////////////////
  551. // Gets the received data from a transfer (upload).
  552. //
  553. // Parameters:
  554. // *pulOffset_: Pointer to a ULONG that will receive
  555. // the offset for the client file
  556. // *ulDataSize_: Pointer to a ULONG that will receive
  557. // the size of the data available in bytes.
  558. // *pvData_: Pointer to a buffer where the received data
  559. // will be copied. NULL can be passed to this
  560. // parameter so that the size can be retrieved
  561. // without copying any data. The application
  562. // can then call this function again to after it
  563. // has allocated a buffer of sufficient size to
  564. // handle the data.
  565. // Returns TRUE if successful. Otherwise, it returns FALSE.
  566. /////////////////////////////////////////////////////////////////
  567. BOOL GetDisconnectParameters(ANTFS_DISCONNECT_PARAMS* pstDisconnectParams_);
  568. /////////////////////////////////////////////////////////////////
  569. // Gets the full parameters for a disconnect command
  570. // received from the host.
  571. //
  572. // Parameters:
  573. // *pstRequestParams_: Pointer to an ANTFS_DISCONNECT_PARAMS
  574. // structure that will receive the details
  575. // of the disconnect request.
  576. // Returns TRUE if successful. Otherwise, it returns FALSE.
  577. // Operation:
  578. // This function makes available all of the parameters received
  579. // from the host when requesting to disconnect from the client.
  580. // These parameters can let the client know whether it is
  581. // returning to broadcast/link state, as well as if it needs
  582. // to make itself undiscoverable for a period of time.
  583. // This information is valid after an ANTFS_RESPONSE_DISCONNECT_PASS
  584. // is received
  585. /////////////////////////////////////////////////////////////////
  586. ANTFS_RETURN SendPairingResponse(BOOL bAccept_);
  587. /////////////////////////////////////////////////////////////////
  588. // Sends a response to a pairing request.
  589. // Parameters:
  590. // bAccept_: Set this value to TRUE to accept the
  591. // pairing request, and FALSE to reject it.
  592. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  593. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  594. // ANTFS_RETURN_BUSY if the library is busy with another request.
  595. // Operation:
  596. // A pairing request will automatically be rejected if no
  597. // response is sent within the pairing timeout, and the
  598. // application will receive an ANTFS_CLIENT_RESPONSE_PAIRING_TIMEOUT
  599. // response.
  600. /////////////////////////////////////////////////////////////////
  601. ANTFS_RETURN SendDownloadResponse(UCHAR ucResponse_, ANTFS_DOWNLOAD_PARAMS* pstDownloadInfo_, ULONG ulDataLength_, void *pvData_);
  602. /////////////////////////////////////////////////////////////////
  603. // Sends the response to a download request from an authenticated
  604. // device.
  605. // Parameters:
  606. // ucResponse_: The response to the download request.
  607. // stDownloadInfo_: Pointer to an ANTFS_CLIENT_DOWNLOAD_PARAMS
  608. // structure holding the parameters of the
  609. // download response.
  610. // ulDataLength_: The byte length of the data block to be
  611. // downloaded to the host device. This is the
  612. // size of the entire file, as specified in
  613. // the directory. Set to zero if no data
  614. // is to be downloaded.
  615. // *pvData_: Pointer to the location where the data
  616. // to be downloaded is stored. The pointer
  617. // should correspond with the beginning of the
  618. // file, without applying any offsets.
  619. // Set to NULL if no data is to be
  620. // downloaded (response rejected).
  621. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  622. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  623. // ANTFS_RETURN_BUSY if the library is busy with another request.
  624. // Operation:
  625. // The data block provided to this function should be the entire
  626. // file. Handling of offsets and CRC calculations is done
  627. // internally within the library.
  628. // Once the request is posted, the application must wait for the
  629. // response from the library. Possible responses are:
  630. // ANTFS_CLIENT_RESPONSE_DOWNLOAD_PASS
  631. // ANTFS_CLIENT_RESPONSE_DOwNLOAD_REJECT
  632. // ANTFS_CLIENT_RESPONSE_DOWNLOAD_FAIL
  633. // ANTFS_CLIENT_RESPONSE_SERIAL_FAIL
  634. /////////////////////////////////////////////////////////////////
  635. ANTFS_RETURN SendUploadResponse(UCHAR ucResponse_, ANTFS_UPLOAD_PARAMS* pstUploadInfo_, ULONG ulDataLength_, void *pvData_);
  636. /////////////////////////////////////////////////////////////////
  637. // Sends the response to an upload request from an authenticated
  638. // device.
  639. // Parameters:
  640. // ucResponse_: The response to the upload request.
  641. // pstUploadInfo_: Pointer to an ANTFS_UPLOAD_PARAMS
  642. // structure holding the parameters of the
  643. // upload response.
  644. // ulDataLength_: The byte length of the data that is
  645. // currently stored at the requested upload
  646. // location. Set to zero if uploading to a
  647. // new index or if the uploaded data will
  648. // overwrite all existing data
  649. // *pvData_: Pointer to the location of the data at the
  650. // requested upload index. Set to NULL
  651. // if no data is available or if the uploaded
  652. // data will overwrite the existing file.
  653. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  654. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  655. // ANTFS_RETURN_BUSY if the library is busy with another request.
  656. // Operation:
  657. // The data block provided to this function should be the entire
  658. // file. Handling of offsets and CRC calculations is done
  659. // internally within the library.
  660. // Once the request is posted, the application must wait for the
  661. // response from the library. Possible responses are:
  662. // ANTFS_CLIENT_RESPONSE_UPLOAD_PASS
  663. // ANTFS_CLIENT_RESPONSE_UPLOAD_REJECT
  664. // ANTFS_CLIENT_RESPONSE_UPLOAD_FAIL
  665. // ANTFS_CLIENT_RESPONSE_SERIAL_FAIL
  666. // Upon receiving ANTFS_CLIENT_RESPONSE_UPLOAD_PASS the uploaded data
  667. // will be available in the transfer buffer. See GetTransferData().
  668. /////////////////////////////////////////////////////////////////
  669. ANTFS_RETURN SendEraseResponse(UCHAR ucResponse_);
  670. /////////////////////////////////////////////////////////////////
  671. // Sends a response to a request to erase a file from an
  672. // authenticated remote device
  673. // Parameters:
  674. // ucResponse_: The response to the erase request.
  675. // Returns ANTFS_RETURN_PASS if successful. Otherwise, it returns
  676. // ANTFS_RETURN_FAIL if the library is in the wrong state, or
  677. // ANTFS_RETURN_BUSY if the library is busy with another request.
  678. /////////////////////////////////////////////////////////////////
  679. ANTFS_CLIENT_RESPONSE WaitForResponse(ULONG ulMilliseconds_);
  680. /////////////////////////////////////////////////////////////////
  681. // Wait for a response from the ANTFS client library
  682. // Parameters:
  683. // ulMilliseconds_: Set this value to the minimum time to
  684. // wait before returning. If the value is
  685. // 0, the function will return immediately.
  686. // If the value is DSI_THREAD_INFINITE, the
  687. // function will not time out.
  688. // If one or more responses are pending before the timeout
  689. // expires the function will return the first response that
  690. // occurred. If no response is pending at the time the timeout
  691. // expires, ANTFS_CLIENT_RESPONSE_NONE is returned.
  692. // Operation:
  693. // Some of the events return parameters associated with the event.
  694. // Possible events and parameters:
  695. // ANTFS_CLIENT_RESPONSE_PAIRING_REQUEST - GetHostName()
  696. // ANTFS_CLIENT_RESPONSE_DOWNLOAD_REQUEST - GetRequestParameters()
  697. // ANTFS_CLIENT_RESPONSE_UPLOAD_REQUEST - GetRequestParameters()
  698. // ANTFS_CLIENT_RESPONSE_ERASE_REQUEST - GetRequestParameters()
  699. // ANTFS_CLIENT_RESPONSE_UPLOAD_PASS - GetTransferData()
  700. /////////////////////////////////////////////////////////////////
  701. };
  702. #endif // ANTFS_CLIENT_CHANNEL_HPP