/* Copyright (c) 2007 Nordic Semiconductor. All Rights Reserved.
 *
 * The information contained herein is property of Nordic Semiconductor ASA.
 * Terms and conditions of usage are described in detail in NORDIC
 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT. 
 *
 * Licensees are granted free, non-transferable use of the information. NO
 * WARRENTY of ANY KIND is provided. This heading must NOT be removed from
 * the file.
 *
 * $LastChangedRevision: 2290 $
 */  

/** @file
 *
 * Device application header file for the Wireless Desktop Protocol. 
 *
 * @author Lasse Olsen 
 *
 * @addtogroup nordic_protocol_wdp Wireless Desktop Protocol
 * @{
*/
 
#include "wdp_common.h"

#ifndef WDP_DEVICE_H__
#define WDP_DEVICE_H__

/** @name Device application functions */
//@{

/**
Initialization function for the Wireless Desktop Protocol (WDP). This function
must be called at least once before any of the remaining WDP functions may be used.

It is recommended that the timer interrupt service routine used by the WDP is not 
enabled until after the WDP is initialized.

@param dev_type specifies the device type. The possible arguemnt are:
@arg @c WDP_MOUSE 
@arg @c WDP_KEYBOARD 
@arg @c WDP_REMOTE 
*/
void wdp_device_init(wdp_dev_types_t dev_type);

/**
Function for sending a pairing request to the dongle 
using the global pairing address and channels defined by 
#WDP_PAIRING_ADDRESS and #WDP_PAIRING_CHANNELS, respectively. 

If a pairing response is received from the dongle the 
device will pair with the address returned in the pairing 
response payload from the dongle, thus the channel set and address 
used for data transmission will be updated.

@retval true if pairing succeeded.
@retval false if pairing failed.
*/
bool wdp_device_request_pairing(void); 

/**
Function for setting the device address. During pairing the device
address is automatically written, and this function is normally needed 
only to rewrite a previous received pairing address on power up. 

Note that the WDP must be in IDLE mode in order for this function to 
have any effect.

@param adr is a pointer to the 5 byte address.

@return
@retval false if failure due to the WDP not beeing in IDLE prior to function call.
@retval true if address successfully written.
 
@sa wdp_device_get_adr(), wdp_device_request_pairing()  
*/
void wdp_device_set_address(uint8_t *adr);

/**
Function for acquiring the number of channel switches needed during 
the previous transmission.

@sa fap_get_ch_switches()
*/
#define wdp_device_get_ch_switches() fap_get_ch_switches();

/**
Function for getting the result of the previous transmit operation. 

@sa fap_tx_success()
*/
#define wdp_device_tx_success() fap_tx_success()

/**
Function for reading out the device address. The device address is received and stored 
either during pairing or by using the function wdp_set_device_adr(). 
This function is typically used in order to read out the device address 
for EEPROM or Flash storage. 

@param a is a pointer to where the 5 byte address shall be written.

@sa wdp_device_set_address(), wdp_device_request_pairing()  
*/
#define wdp_device_get_adr(a) fap_get_address(FAP_DEVICE1, a)

/**
Function for starting transmission of data from device to host.

@param dst specifies the source address for the data to be transmitted.
Note that the first data byte (byte 0) is reserved for protocol commands 
and any data written to this byte will be ignored and overwritten by the protocol. 
The function will transmit a total of #WDP_DEVICE_PL_LENGTH number of bytes.

@param length specifies the number of bytes to be transmitted. The number of
bytes may not exceed #WDP_MAX_UL_PL_LENGTH.

@return Returns the transmission was started. 

@retval true if data were successfully provided to protocol for transmission.

@retval false if failure on starting transmission. This can be caused by the length
of the payload exceeding #fap_max_ul_pl_length bytes or any of the requirements for
fap_tx_data() not being fulfilled. 

@sa wdp_device_get_mode(), wdp_device_get_tries(), wdp_device_tx_success()

*/
bool wdp_device_send_data(uint8_t *dat, uint8_t length);

/**
Function for acquiring the number of transmit attempts needed during 
the previous transmission.

@sa fap_get_tries()
*/
#define wdp_device_get_tries() fap_get_tries()

/**
@sa fap_get_ch_offset().  
*/ 
#define wdp_device_get_ch_offset() fap_get_ch_offset()

/**
@sa fap_ch_sync_enable().  
*/ 
#define wdp_device_ch_sync_enable() fap_ch_sync_enable()

/**
@sa fap_ch_sync_disable().  
*/ 
#define wdp_device_ch_sync_disable() fap_ch_sync_disable()

/**
Function for processing WDP events. This function monitors WDP timing variables
and transmits a new "keep alive" message whenever necessary in order to maintain a 
continuous data link set up by wdp_connect(). This function only has to be called 
whenever a continues data link is activated.

@sa wdp_device_connect()
*/
void wdp_device_process_events(void); 

/**
Function for setting up a continuous data link between device and host.
This function may be useful in cases where it is crucial for
the host to distinguish between a "silent" device and a device that
for some reason has lost its radio connection to the host. After execution of 
this function, the device will start transmitting dummy "keep alive" 
messages periodically with an interval set up by #WDP_MOUSE_KA_INTERVAL,
#WDP_KEYBOARD_KA_INTERVAL or #WDP_REMOTE_KA_INTERVAL, dependent of the
device type. However, the interval will between each dummy package will be 
extended whenever a data package is sent by the application, thus these dummy 
messages will not be transmitted as long as the link is kept alive by actual 
user data. 
 
Note that the device power consumption will increase when this
continuous link is activated.  

@sa wdp_device_disconnect()
*/
void wdp_device_connect(void);

/**
Function for shutting down the continuous data link set up by 
wdp_connect().  

@sa wdp_device_connect()
*/
void wdp_device_disconnect(void);


/** Function for reading received downlink data from host. The host may piggyback 
a data payload on any acknowledge sent in return on a device to host transmission. 
This function can be used by the application to read this payload.

@param dst a pointer to where the received data shall be copied. 

@return
Returns the number of bytes received and copied do *dst. The destination should be
able to accomodate minimum #WDP_MAX_DL_PL_LENGTH bytes.

@sa wdp_device_send_data()

*/ 
bool wdp_device_get_downlink_data(uint8_t *dst, uint8_t *length);
 
/**
This function returns the status of the continuous 
link established by wdp_connect(). On failure of
transmitting a dummy "keep alive" message, the
protocol automatically goes to "disconnected"
and the continuous data transmission will be shut
down.   

@return 
@retval true if the device is connected.
@retval false if the device is disconnected. 
*/ 
bool wdp_device_connected(void);
//@}

#endif

/** @} */