Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit a9d77d24 authored by TreeHugger Robot's avatar TreeHugger Robot Committed by Android (Google) Code Review
Browse files

Merge changes I8e37ac14,Ic8642a39,I06eb6d80 into tm-dev 

* changes:
  Revert "Queue discovery and device inquiry while bonding"
  Revert "Make SDP and inquiry request dequeue and execute more comprehensive and"
  Revert "Immediately execute instead of queueing request for LE service discovery"
parents 71f951b4 3da8e931

system/bta/dm/bta_dm_act.cc

+23 −59
Original line number Original line Diff line number Diff line
@@ -44,7 +44,6 @@ 
#include "main/shim/shim.h"

#include "main/shim/shim.h"

#include "osi/include/allocator.h"

#include "osi/include/allocator.h"

#include "osi/include/compat.h"

#include "osi/include/compat.h"

#include "osi/include/fixed_queue.h"

#include "osi/include/log.h"

#include "osi/include/log.h"

#include "osi/include/osi.h"

#include "osi/include/osi.h"

#include "stack/btm/btm_ble_int.h"

#include "stack/btm/btm_ble_int.h"
@@ -321,8 +320,6 @@ void BTA_dm_on_hw_off() { 
  /* hw is ready, go on with BTA DM initialization */

  /* hw is ready, go on with BTA DM initialization */

  alarm_free(bta_dm_search_cb.search_timer);

  alarm_free(bta_dm_search_cb.search_timer);

  alarm_free(bta_dm_search_cb.gatt_close_timer);

  alarm_free(bta_dm_search_cb.gatt_close_timer);

  osi_free(bta_dm_search_cb.p_pending_search);

  fixed_queue_free(bta_dm_search_cb.pending_discovery_queue, osi_free);

  memset(&bta_dm_search_cb, 0, sizeof(bta_dm_search_cb));

  memset(&bta_dm_search_cb, 0, sizeof(bta_dm_search_cb));

}

}
@@ -342,8 +339,6 @@ void BTA_dm_on_hw_on() { 
  /* hw is ready, go on with BTA DM initialization */

  /* hw is ready, go on with BTA DM initialization */

  alarm_free(bta_dm_search_cb.search_timer);

  alarm_free(bta_dm_search_cb.search_timer);

  alarm_free(bta_dm_search_cb.gatt_close_timer);

  alarm_free(bta_dm_search_cb.gatt_close_timer);

  osi_free(bta_dm_search_cb.p_pending_search);

  fixed_queue_free(bta_dm_search_cb.pending_discovery_queue, osi_free);

  memset(&bta_dm_search_cb, 0, sizeof(bta_dm_search_cb));

  memset(&bta_dm_search_cb, 0, sizeof(bta_dm_search_cb));

  /*

  /*

   * TODO: Should alarm_free() the bta_dm_search_cb timers during

   * TODO: Should alarm_free() the bta_dm_search_cb timers during
@@ -352,7 +347,6 @@ void BTA_dm_on_hw_on() { 
  bta_dm_search_cb.search_timer = alarm_new("bta_dm_search.search_timer");

  bta_dm_search_cb.search_timer = alarm_new("bta_dm_search.search_timer");

  bta_dm_search_cb.gatt_close_timer =

  bta_dm_search_cb.gatt_close_timer =

      alarm_new("bta_dm_search.gatt_close_timer");

      alarm_new("bta_dm_search.gatt_close_timer");

  bta_dm_search_cb.pending_discovery_queue = fixed_queue_new(SIZE_MAX);





  memset(&bta_dm_conn_srvcs, 0, sizeof(bta_dm_conn_srvcs));

  memset(&bta_dm_conn_srvcs, 0, sizeof(bta_dm_conn_srvcs));

  memset(&bta_dm_di_cb, 0, sizeof(tBTA_DM_DI_CB));

  memset(&bta_dm_di_cb, 0, sizeof(tBTA_DM_DI_CB));
@@ -996,7 +990,7 @@ static bool bta_dm_read_remote_device_name(const RawAddress& bd_addr, 
void bta_dm_inq_cmpl(uint8_t num) {

void bta_dm_inq_cmpl(uint8_t num) {

  if (bta_dm_search_get_state() == BTA_DM_SEARCH_CANCELLING) {

  if (bta_dm_search_get_state() == BTA_DM_SEARCH_CANCELLING) {

    bta_dm_search_set_state(BTA_DM_SEARCH_IDLE);

    bta_dm_search_set_state(BTA_DM_SEARCH_IDLE);

    bta_dm_execute_queued_request();

    bta_dm_search_cancel_cmpl();

    return;

    return;

  }

  }
@@ -1295,7 +1289,6 @@ void bta_dm_search_cmpl() { 
  /* no BLE connection, i.e. Classic service discovery end */

  /* no BLE connection, i.e. Classic service discovery end */

  if (conn_id == GATT_INVALID_CONN_ID) {

  if (conn_id == GATT_INVALID_CONN_ID) {

    bta_dm_search_cb.p_search_cback(BTA_DM_DISC_CMPL_EVT, nullptr);

    bta_dm_search_cb.p_search_cback(BTA_DM_DISC_CMPL_EVT, nullptr);

    bta_dm_execute_queued_request();

    return;

    return;

  }

  }
@@ -1306,7 +1299,6 @@ void bta_dm_search_cmpl() { 
  if (count == 0) {

  if (count == 0) {

    LOG_INFO("Empty GATT database - no BLE services discovered");

    LOG_INFO("Empty GATT database - no BLE services discovered");

    bta_dm_search_cb.p_search_cback(BTA_DM_DISC_CMPL_EVT, nullptr);

    bta_dm_search_cb.p_search_cback(BTA_DM_DISC_CMPL_EVT, nullptr);

    bta_dm_execute_queued_request();

    return;

    return;

  }

  }
@@ -1331,8 +1323,6 @@ void bta_dm_search_cmpl() { 
  bta_dm_search_cb.p_search_cback(BTA_DM_DISC_BLE_RES_EVT, &result);

  bta_dm_search_cb.p_search_cback(BTA_DM_DISC_BLE_RES_EVT, &result);





  bta_dm_search_cb.p_search_cback(BTA_DM_DISC_CMPL_EVT, nullptr);

  bta_dm_search_cb.p_search_cback(BTA_DM_DISC_CMPL_EVT, nullptr);



  bta_dm_execute_queued_request();

}

}





/*******************************************************************************

/*******************************************************************************
@@ -1429,13 +1419,13 @@ void bta_dm_free_sdp_db() { 
 *

 *

 * Function         bta_dm_queue_search

 * Function         bta_dm_queue_search

 *

 *

 * Description      Queues search command

 * Description      Queues search command while search is being cancelled

 *

 *

 * Returns          void

 * Returns          void

 *

 *

 ******************************************************************************/

 ******************************************************************************/

void bta_dm_queue_search(tBTA_DM_MSG* p_data) {

void bta_dm_queue_search(tBTA_DM_MSG* p_data) {

  osi_free_and_reset((void**)&bta_dm_search_cb.p_pending_search);

  bta_dm_search_clear_queue();

  bta_dm_search_cb.p_pending_search =

  bta_dm_search_cb.p_pending_search =

      (tBTA_DM_MSG*)osi_malloc(sizeof(tBTA_DM_API_SEARCH));

      (tBTA_DM_MSG*)osi_malloc(sizeof(tBTA_DM_API_SEARCH));

  memcpy(bta_dm_search_cb.p_pending_search, p_data, sizeof(tBTA_DM_API_SEARCH));

  memcpy(bta_dm_search_cb.p_pending_search, p_data, sizeof(tBTA_DM_API_SEARCH));
@@ -1445,76 +1435,50 @@ void bta_dm_queue_search(tBTA_DM_MSG* p_data) { 
 *

 *

 * Function         bta_dm_queue_disc

 * Function         bta_dm_queue_disc

 *

 *

 * Description      Queues discovery command

 * Description      Queues discovery command while search is being cancelled

 *

 *

 * Returns          void

 * Returns          void

 *

 *

 ******************************************************************************/

 ******************************************************************************/

void bta_dm_queue_disc(tBTA_DM_MSG* p_data) {

void bta_dm_queue_disc(tBTA_DM_MSG* p_data) {

  tBTA_DM_MSG* p_pending_discovery =

  bta_dm_search_clear_queue();

  bta_dm_search_cb.p_pending_discovery =

      (tBTA_DM_MSG*)osi_malloc(sizeof(tBTA_DM_API_DISCOVER));

      (tBTA_DM_MSG*)osi_malloc(sizeof(tBTA_DM_API_DISCOVER));

  memcpy(p_pending_discovery, p_data, sizeof(tBTA_DM_API_DISCOVER));

  memcpy(bta_dm_search_cb.p_pending_discovery, p_data,

  fixed_queue_enqueue(bta_dm_search_cb.pending_discovery_queue,

         sizeof(tBTA_DM_API_DISCOVER));

                      p_pending_discovery);

}

}





/*******************************************************************************

/*******************************************************************************

 *

 *

 * Function         bta_dm_execute_queued_request

 * Function         bta_dm_search_clear_queue

 *

 *

 * Description      Executes queued request if one exists

 * Description      Clears the queue if API search cancel is called

 *

 *

 * Returns          void

 * Returns          void

 *

 *

 ******************************************************************************/

 ******************************************************************************/

void bta_dm_execute_queued_request() {

void bta_dm_search_clear_queue() {

  if (bta_dm_search_cb.p_pending_search) {

  osi_free_and_reset((void**)&bta_dm_search_cb.p_pending_search);

    // Updated queued event to search event to trigger start search

  osi_free_and_reset((void**)&bta_dm_search_cb.p_pending_discovery);

    if (bta_dm_search_cb.p_pending_search->hdr.event ==

        BTA_DM_API_QUEUE_SEARCH_EVT) {

      bta_dm_search_cb.p_pending_search->hdr.event = BTA_DM_API_SEARCH_EVT;

    }

    LOG_INFO("%s Start pending search", __func__);

    bta_sys_sendmsg(bta_dm_search_cb.p_pending_search);

    bta_dm_search_cb.p_pending_search = NULL;

  } else {

    tBTA_DM_MSG* p_pending_discovery = (tBTA_DM_MSG*)fixed_queue_try_dequeue(

        bta_dm_search_cb.pending_discovery_queue);

    if (p_pending_discovery) {

      if (p_pending_discovery->hdr.event == BTA_DM_API_QUEUE_DISCOVER_EVT) {

        p_pending_discovery->hdr.event = BTA_DM_API_DISCOVER_EVT;

      }

      LOG_INFO("%s Start pending discovery", __func__);

      bta_sys_sendmsg(p_pending_discovery);

    }

  }

}



/*******************************************************************************

 *

 * Function         bta_dm_is_search_request_queued

 *

 * Description      Checks if there is a queued search request

 *

 * Returns          bool

 *

 ******************************************************************************/

bool bta_dm_is_search_request_queued() {

  return bta_dm_search_cb.p_pending_search != NULL;

}

}





/*******************************************************************************

/*******************************************************************************

 *

 *

 * Function         bta_dm_search_clear_queue

 * Function         bta_dm_search_cancel_cmpl

 *

 *

 * Description      Clears the queue if API search cancel is called

 * Description      Search cancel is complete

 *

 *

 * Returns          void

 * Returns          void

 *

 *

 ******************************************************************************/

 ******************************************************************************/

void bta_dm_search_clear_queue() {

void bta_dm_search_cancel_cmpl() {

  osi_free_and_reset((void**)&bta_dm_search_cb.p_pending_search);

  if (bta_dm_search_cb.p_pending_search) {

  fixed_queue_flush(bta_dm_search_cb.pending_discovery_queue, osi_free);

    bta_sys_sendmsg(bta_dm_search_cb.p_pending_search);

    bta_dm_search_cb.p_pending_search = NULL;

  } else if (bta_dm_search_cb.p_pending_discovery) {

    bta_sys_sendmsg(bta_dm_search_cb.p_pending_discovery);

    bta_dm_search_cb.p_pending_discovery = NULL;

  }

}

}





/*******************************************************************************

/*******************************************************************************

system/bta/dm/bta_dm_api.cc

+5 −15
Original line number Original line Diff line number Diff line
@@ -80,16 +80,11 @@ void BTA_DmSetDeviceName(const char* p_name) { 
 * Returns          void

 * Returns          void

 *

 *

 ******************************************************************************/

 ******************************************************************************/

void BTA_DmSearch(tBTA_DM_SEARCH_CBACK* p_cback, bool is_bonding_or_sdp) {

void BTA_DmSearch(tBTA_DM_SEARCH_CBACK* p_cback) {

  tBTA_DM_API_SEARCH* p_msg =

  tBTA_DM_API_SEARCH* p_msg =

      (tBTA_DM_API_SEARCH*)osi_calloc(sizeof(tBTA_DM_API_SEARCH));

      (tBTA_DM_API_SEARCH*)osi_calloc(sizeof(tBTA_DM_API_SEARCH));





  /* Queue request if a device is bonding or performing service discovery */

  if (is_bonding_or_sdp) {

    p_msg->hdr.event = BTA_DM_API_QUEUE_SEARCH_EVT;

  } else {

  p_msg->hdr.event = BTA_DM_API_SEARCH_EVT;

  p_msg->hdr.event = BTA_DM_API_SEARCH_EVT;

  }

  p_msg->p_cback = p_cback;

  p_msg->p_cback = p_cback;





  bta_sys_sendmsg(p_msg);

  bta_sys_sendmsg(p_msg);
@@ -106,8 +101,6 @@ void BTA_DmSearch(tBTA_DM_SEARCH_CBACK* p_cback, bool is_bonding_or_sdp) { 
 *

 *

 ******************************************************************************/

 ******************************************************************************/

void BTA_DmSearchCancel(void) {

void BTA_DmSearchCancel(void) {

  bta_dm_search_clear_queue();



  switch (bta_dm_search_get_state()) {

  switch (bta_dm_search_get_state()) {

    case BTA_DM_SEARCH_IDLE:

    case BTA_DM_SEARCH_IDLE:

      bta_dm_search_cancel_notify();

      bta_dm_search_cancel_notify();
@@ -117,6 +110,7 @@ void BTA_DmSearchCancel(void) { 
      bta_dm_search_cancel();

      bta_dm_search_cancel();

      break;

      break;

    case BTA_DM_SEARCH_CANCELLING:

    case BTA_DM_SEARCH_CANCELLING:

      bta_dm_search_clear_queue();

      bta_dm_search_cancel_notify();

      bta_dm_search_cancel_notify();

      break;

      break;

    case BTA_DM_DISCOVER_ACTIVE:

    case BTA_DM_DISCOVER_ACTIVE:
@@ -138,15 +132,11 @@ void BTA_DmSearchCancel(void) { 
 *

 *

 ******************************************************************************/

 ******************************************************************************/

void BTA_DmDiscover(const RawAddress& bd_addr, tBTA_DM_SEARCH_CBACK* p_cback,

void BTA_DmDiscover(const RawAddress& bd_addr, tBTA_DM_SEARCH_CBACK* p_cback,

                    tBT_TRANSPORT transport, bool is_bonding_or_sdp) {

                    tBT_TRANSPORT transport) {

  tBTA_DM_API_DISCOVER* p_msg =

  tBTA_DM_API_DISCOVER* p_msg =

      (tBTA_DM_API_DISCOVER*)osi_calloc(sizeof(tBTA_DM_API_DISCOVER));

      (tBTA_DM_API_DISCOVER*)osi_calloc(sizeof(tBTA_DM_API_DISCOVER));





  if (is_bonding_or_sdp) {

    p_msg->hdr.event = BTA_DM_API_QUEUE_DISCOVER_EVT;

  } else {

  p_msg->hdr.event = BTA_DM_API_DISCOVER_EVT;

  p_msg->hdr.event = BTA_DM_API_DISCOVER_EVT;

  }

  p_msg->bd_addr = bd_addr;

  p_msg->bd_addr = bd_addr;

  p_msg->transport = transport;

  p_msg->transport = transport;

  p_msg->p_cback = p_cback;

  p_msg->p_cback = p_cback;

system/bta/dm/bta_dm_int.h

+5 −8
Original line number Original line Diff line number Diff line
@@ -70,19 +70,17 @@ enum { 
  BTA_DM_SDP_RESULT_EVT,

  BTA_DM_SDP_RESULT_EVT,

  BTA_DM_SEARCH_CMPL_EVT,

  BTA_DM_SEARCH_CMPL_EVT,

  BTA_DM_DISCOVERY_RESULT_EVT,

  BTA_DM_DISCOVERY_RESULT_EVT,

  BTA_DM_DISC_CLOSE_TOUT_EVT,

  BTA_DM_DISC_CLOSE_TOUT_EVT

  BTA_DM_API_QUEUE_SEARCH_EVT,

  BTA_DM_API_QUEUE_DISCOVER_EVT

};

};





/* data type for BTA_DM_API_SEARCH_EVT and BTA_DM_API_QUEUE_SEARCH_EVT */

/* data type for BTA_DM_API_SEARCH_EVT */

typedef struct {

typedef struct {

  BT_HDR_RIGID hdr;

  BT_HDR_RIGID hdr;

  tBTA_SERVICE_MASK services;

  tBTA_SERVICE_MASK services;

  tBTA_DM_SEARCH_CBACK* p_cback;

  tBTA_DM_SEARCH_CBACK* p_cback;

} tBTA_DM_API_SEARCH;

} tBTA_DM_API_SEARCH;





/* data type for BTA_DM_API_DISCOVER_EVT and BTA_DM_API_QUEUE_DISCOVER_EVT */

/* data type for BTA_DM_API_DISCOVER_EVT */

typedef struct {

typedef struct {

  BT_HDR_RIGID hdr;

  BT_HDR_RIGID hdr;

  RawAddress bd_addr;

  RawAddress bd_addr;
@@ -358,7 +356,7 @@ typedef struct { 
  alarm_t* search_timer;

  alarm_t* search_timer;

  uint8_t service_index;

  uint8_t service_index;

  tBTA_DM_MSG* p_pending_search;

  tBTA_DM_MSG* p_pending_search;

  fixed_queue_t* pending_discovery_queue;

  tBTA_DM_MSG* p_pending_discovery;

  bool wait_disc;

  bool wait_disc;

  bool sdp_results;

  bool sdp_results;

  bluetooth::Uuid uuid;

  bluetooth::Uuid uuid;
@@ -535,9 +533,8 @@ extern void bta_dm_search_result(tBTA_DM_MSG* p_data); 
extern void bta_dm_discovery_cmpl(tBTA_DM_MSG* p_data);

extern void bta_dm_discovery_cmpl(tBTA_DM_MSG* p_data);

extern void bta_dm_queue_search(tBTA_DM_MSG* p_data);

extern void bta_dm_queue_search(tBTA_DM_MSG* p_data);

extern void bta_dm_queue_disc(tBTA_DM_MSG* p_data);

extern void bta_dm_queue_disc(tBTA_DM_MSG* p_data);

extern void bta_dm_execute_queued_request();

extern bool bta_dm_is_search_request_queued();

extern void bta_dm_search_clear_queue();

extern void bta_dm_search_clear_queue();

extern void bta_dm_search_cancel_cmpl();

extern void bta_dm_search_cancel_notify();

extern void bta_dm_search_cancel_notify();

extern void bta_dm_disc_rmt_name(tBTA_DM_MSG* p_data);

extern void bta_dm_disc_rmt_name(tBTA_DM_MSG* p_data);

extern tBTA_DM_PEER_DEVICE* bta_dm_find_peer_device(

extern tBTA_DM_PEER_DEVICE* bta_dm_find_peer_device(

system/bta/dm/bta_dm_main.cc

+1 −21
Original line number Original line Diff line number Diff line
@@ -82,12 +82,6 @@ bool bta_dm_search_sm_execute(BT_HDR_RIGID* p_msg) { 
        case BTA_DM_DISC_CLOSE_TOUT_EVT:

        case BTA_DM_DISC_CLOSE_TOUT_EVT:

          bta_dm_close_gatt_conn(message);

          bta_dm_close_gatt_conn(message);

          break;

          break;

        case BTA_DM_API_QUEUE_SEARCH_EVT:

          bta_dm_queue_search(message);

          break;

        case BTA_DM_API_QUEUE_DISCOVER_EVT:

          bta_dm_queue_disc(message);

          break;

      }

      }

      break;

      break;

    case BTA_DM_SEARCH_ACTIVE:

    case BTA_DM_SEARCH_ACTIVE:
@@ -107,20 +101,14 @@ bool bta_dm_search_sm_execute(BT_HDR_RIGID* p_msg) { 
        case BTA_DM_DISC_CLOSE_TOUT_EVT:

        case BTA_DM_DISC_CLOSE_TOUT_EVT:

          bta_dm_close_gatt_conn(message);

          bta_dm_close_gatt_conn(message);

          break;

          break;

        case BTA_DM_API_DISCOVER_EVT:

        case BTA_DM_API_QUEUE_DISCOVER_EVT:

          bta_dm_queue_disc(message);

          break;

      }

      }

      break;

      break;

    case BTA_DM_SEARCH_CANCELLING:

    case BTA_DM_SEARCH_CANCELLING:

      switch (p_msg->event) {

      switch (p_msg->event) {

        case BTA_DM_API_SEARCH_EVT:

        case BTA_DM_API_SEARCH_EVT:

        case BTA_DM_API_QUEUE_SEARCH_EVT:

          bta_dm_queue_search(message);

          bta_dm_queue_search(message);

          break;

          break;

        case BTA_DM_API_DISCOVER_EVT:

        case BTA_DM_API_DISCOVER_EVT:

        case BTA_DM_API_QUEUE_DISCOVER_EVT:

          bta_dm_queue_disc(message);

          bta_dm_queue_disc(message);

          break;

          break;

        case BTA_DM_SDP_RESULT_EVT:

        case BTA_DM_SDP_RESULT_EVT:
@@ -130,7 +118,7 @@ bool bta_dm_search_sm_execute(BT_HDR_RIGID* p_msg) { 
          bta_dm_search_set_state(BTA_DM_SEARCH_IDLE);

          bta_dm_search_set_state(BTA_DM_SEARCH_IDLE);

          bta_dm_free_sdp_db();

          bta_dm_free_sdp_db();

          bta_dm_search_cancel_notify();

          bta_dm_search_cancel_notify();

          bta_dm_execute_queued_request();

          bta_dm_search_cancel_cmpl();

          break;

          break;

      }

      }

      break;

      break;
@@ -148,14 +136,6 @@ bool bta_dm_search_sm_execute(BT_HDR_RIGID* p_msg) { 
        case BTA_DM_DISCOVERY_RESULT_EVT:

        case BTA_DM_DISCOVERY_RESULT_EVT:

          bta_dm_disc_result(message);

          bta_dm_disc_result(message);

          break;

          break;

        case BTA_DM_API_SEARCH_EVT:

        case BTA_DM_API_QUEUE_SEARCH_EVT:

          bta_dm_queue_search(message);

          break;

        case BTA_DM_API_DISCOVER_EVT:

        case BTA_DM_API_QUEUE_DISCOVER_EVT:

          bta_dm_queue_disc(message);

          break;

      }

      }

      break;

      break;

  }

  }

system/bta/include/bta_api.h

+3 −5
Original line number Original line Diff line number Diff line
@@ -710,15 +710,13 @@ extern bool BTA_DmSetVisibility(bt_scan_mode_t mode); 
 *                  first performs an inquiry; for each device found from the

 *                  first performs an inquiry; for each device found from the

 *                  inquiry it gets the remote name of the device.  If

 *                  inquiry it gets the remote name of the device.  If

 *                  parameter services is nonzero, service discovery will be

 *                  parameter services is nonzero, service discovery will be

 *                  performed on each device for the services specified. If the

 *                  performed on each device for the services specified.

 *                  parameter is_bonding_or_sdp is true, the request will be

 *                  queued until bonding or sdp completes

 *

 *

 *

 *

 * Returns          void

 * Returns          void

 *

 *

 ******************************************************************************/

 ******************************************************************************/

extern void BTA_DmSearch(tBTA_DM_SEARCH_CBACK* p_cback, bool is_bonding_or_sdp);

extern void BTA_DmSearch(tBTA_DM_SEARCH_CBACK* p_cback);





/*******************************************************************************

/*******************************************************************************

 *

 *
@@ -746,7 +744,7 @@ extern void BTA_DmSearchCancel(void); 
 ******************************************************************************/

 ******************************************************************************/

extern void BTA_DmDiscover(const RawAddress& bd_addr,

extern void BTA_DmDiscover(const RawAddress& bd_addr,

                           tBTA_DM_SEARCH_CBACK* p_cback,

                           tBTA_DM_SEARCH_CBACK* p_cback,

                           tBT_TRANSPORT transport, bool is_bonding_or_sdp);

                           tBT_TRANSPORT transport);





/*******************************************************************************

/*******************************************************************************

 *

 *