Trait bluenrg::gap::Commands[−][src]

pub trait Commands {
    type Error;
    fn set_nondiscoverable(&mut self) -> Result<(), Self::Error>;

    fn set_limited_discoverable<'a, 'b>(
        &mut self, 
        params: &DiscoverableParameters<'a, 'b>
    ) -> Result<(), Error<Self::Error>>;

    fn set_discoverable<'a, 'b>(
        &mut self, 
        params: &DiscoverableParameters<'a, 'b>
    ) -> Result<(), Error<Self::Error>>;

    fn set_direct_connectable(
        &mut self, 
        params: &DirectConnectableParameters
    ) -> Result<(), Error<Self::Error>>;

    fn set_io_capability(
        &mut self, 
        capability: IoCapability
    ) -> Result<(), Self::Error>;

    fn set_authentication_requirement(
        &mut self, 
        requirements: &AuthenticationRequirements
    ) -> Result<(), Error<Self::Error>>;

    fn set_authorization_requirement(
        &mut self, 
        conn_handle: ConnectionHandle, 
        authorization_required: bool
    ) -> Result<(), Self::Error>;

    fn pass_key_response(
        &mut self, 
        conn_handle: ConnectionHandle, 
        pin: u32
    ) -> Result<(), Error<Self::Error>>;

    fn authorization_response(
        &mut self, 
        conn_handle: ConnectionHandle, 
        authorization: Authorization
    ) -> Result<(), Self::Error>;

    fn init(
        &mut self, 
        role: Role, 
        privacy_enabled: bool, 
        dev_name_characteristic_len: usize
    ) -> Result<(), Self::Error>;

    fn set_nonconnectable(
        &mut self, 
        advertising_type: AdvertisingType, 
        address_type: AddressType
    ) -> Result<(), Error<Self::Error>>;

    fn set_undirected_connectable(
        &mut self, 
        filter_policy: AdvertisingFilterPolicy, 
        address_type: AddressType
    ) -> Result<(), Error<Self::Error>>;

    fn peripheral_security_request(
        &mut self, 
        params: &SecurityRequestParameters
    ) -> Result<(), Self::Error>;

    fn update_advertising_data(
        &mut self, 
        data: &[u8]
    ) -> Result<(), Error<Self::Error>>;

    fn delete_ad_type(
        &mut self, 
        ad_type: AdvertisingDataType
    ) -> Result<(), Self::Error>;

    fn get_security_level(&mut self) -> Result<(), Self::Error>;

    fn set_event_mask(&mut self, flags: EventFlags) -> Result<(), Self::Error>;

    fn configure_white_list(&mut self) -> Result<(), Self::Error>;

    fn terminate(
        &mut self, 
        conn_handle: ConnectionHandle, 
        reason: Status<Status>
    ) -> Result<(), Error<Self::Error>>;

    fn clear_security_database(&mut self) -> Result<(), Self::Error>;

    fn allow_rebond(
        &mut self, 
        conn_handle: ConnectionHandle
    ) -> Result<(), Self::Error>;

    fn start_limited_discovery_procedure(
        &mut self, 
        params: &DiscoveryProcedureParameters
    ) -> Result<(), Self::Error>;

    fn start_general_discovery_procedure(
        &mut self, 
        params: &DiscoveryProcedureParameters
    ) -> Result<(), Self::Error>;

    fn start_name_discovery_procedure(
        &mut self, 
        params: &NameDiscoveryProcedureParameters
    ) -> Result<(), Self::Error>;

    fn start_auto_connection_establishment<'a>(
        &mut self, 
        params: &AutoConnectionEstablishmentParameters<'a>
    ) -> Result<(), Error<Self::Error>>;

    fn start_general_connection_establishment(
        &mut self, 
        params: &GeneralConnectionEstablishmentParameters
    ) -> Result<(), Self::Error>;

    fn start_selective_connection_establishment<'a>(
        &mut self, 
        params: &SelectiveConnectionEstablishmentParameters<'a>
    ) -> Result<(), Error<Self::Error>>;

    fn create_connection(
        &mut self, 
        params: &ConnectionParameters
    ) -> Result<(), Self::Error>;

    fn terminate_procedure(
        &mut self, 
        procedure: Procedure
    ) -> Result<(), Error<Self::Error>>;

    fn start_connection_update(
        &mut self, 
        params: &ConnectionUpdateParameters
    ) -> Result<(), Self::Error>;

    fn send_pairing_request(
        &mut self, 
        params: &PairingRequest
    ) -> Result<(), Self::Error>;

    fn resolve_private_address(
        &mut self, 
        addr: BdAddr
    ) -> Result<(), Self::Error>;

    fn get_bonded_devices(&mut self) -> Result<(), Self::Error>;

    fn set_broadcast_mode(
        &mut self, 
        params: &BroadcastModeParameters
    ) -> Result<(), Error<Self::Error>>;

    fn start_observation_procedure(
        &mut self, 
        params: &ObservationProcedureParameters
    ) -> Result<(), Self::Error>;

    fn is_device_bonded(
        &mut self, 
        addr: PeerAddrType
    ) -> Result<(), Self::Error>;
}

GAP-specific commands for the ActiveBlueNRG.

Associated Types

Type of communication errors.

Required Methods

Set the device in non-discoverable mode. This command will disable the LL advertising and put the device in standby state.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

Set the device in limited discoverable mode.

Limited discoverability is defined in in GAP specification volume 3, section 9.2.3. The device will be discoverable for maximum period of TGAP (lim_adv_timeout) = 180 seconds (from errata). The advertising can be disabled at any time by issuing a set_nondiscoverable command.

Errors

Generated evenst

When the controller receives the command, it will generate a command status event. The controller starts the advertising after this and when advertising timeout happens (i.e. limited discovery period has elapsed), the controller generates an GAP Limited Discoverable Complete event.

Set the device in discoverable mode.

Limited discoverability is defined in in GAP specification volume 3, section 9.2.4. The device will be discoverable for maximum period of TGAP (lim_adv_timeout) = 180 seconds (from errata). The advertising can be disabled at any time by issuing a set_nondiscoverable command.

Errors

Generated evenst

A Command Complete event is generated.

Set the device in direct connectable mode.

Direct connectable mode is defined in GAP specification Volume 3, Section 9.3.3). Device uses direct connectable mode to advertise using either High Duty cycle advertisement events or Low Duty cycle advertisement events and the address as what is specified in the Own Address Type parameter. The Advertising Type parameter in the command specifies the type of the advertising used.

When the ms feature is not enabled, the device will be in directed connectable mode only for 1.28 seconds. If no connection is established within this duration, the device enters non discoverable mode and advertising will have to be again enabled explicitly.

When the ms feature is enabled, the advertising interval is explicitly provided in the parameters.

Errors

Generated evenst

A Command Complete event is generated.

Set the IO capabilities of the device.

This command has to be given only when the device is not in a connected state.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

Set the authentication requirements for the device.

This command has to be given only when the device is not in a connected state.

Errors

Generated events

Set the authorization requirements of the device.

This command has to be given when connected to a device if authorization is required to access services which require authorization.

Errors

Only underlying communication errors are reported.

Generated events

This command should be send by the host in response to the GAP Pass Key Request event.

pin contains the pass key which will be used during the pairing process.

Errors

  • BadFixedPin if the pin is greater than 999999.
  • Underlying communication errors.

Generated events

This command should be send by the host in response to the GAP Authorization Request event.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

Register the GAP service with the GATT.

The device name characteristic and appearance characteristic are added by default and the handles of these characteristics are returned in the event data.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

Put the device into non-connectable mode.

This mode does not support connection. The privacy setting done in the init command plays a role in deciding the valid parameters for this command. If privacy was not enabled, address_type may be Public or Random. If privacy was enabled, address_type may be ResolvablePrivate or NonResolvablePrivate.

Errors

  • BadAdvertisingType if the advertising type is not one of the supported modes. It must be ScannableUndirected or (NonConnectableUndirected)[AdvertisingType::NonConnectableUndirected).
  • Underlying communication errors.

Generated events

A Command Complete event is generated.

Put the device into undirected connectable mode.

The privacy setting done in the init command plays a role in deciding the valid parameters for this command.

Errors

Generated events

A Command Complete event is generated.

This command has to be issued to notify the central device of the security requirements of the peripheral.

Errors

Only underlying communication errors are reported.

Generated events

A command status event will be generated when a valid command is received. On completion of the command, i.e. when the security request is successfully transmitted to the master, a GAP Peripheral Security Initiated vendor-specific event will be generated.

This command can be used to update the advertising data for a particular AD type. If the AD type specified does not exist, then it is added to the advertising data. If the overall advertising data length is more than 31 octets after the update, then the command is rejected and the old data is retained.

Errors

Generated events

A Command Complete event is generated.

This command can be used to delete the specified AD type from the advertisement data if present.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

This command can be used to get the current security settings of the device.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

Allows masking events from the GAP.

The default configuration is all the events masked.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

Configure the controller's white list with devices that are present in the security database.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

Command the controller to terminate the connection.

Errors

Generated events

The controller will generate a command status event when the command is received and a Disconnection Complete event will be generated when the link is disconnected.

Clear the security database. All the devices in the security database will be removed.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated.

This command should be given by the application when it receives the GAP Bond Lost event if it wants the re-bonding to happen successfully. If this command is not given on receiving the event, the bonding procedure will timeout.

Errors

Only underlying communication errors are reported.

Generated events

A Command Complete event is generated. Even if the command is given when it is not valid, success will be returned but internally it will have no effect.

Start the limited discovery procedure.

The controller is commanded to start active scanning. When this procedure is started, only the devices in limited discoverable mode are returned to the upper layers.

Errors

Only underlying communication errors are reported.

Generated events

A command status event is generated as soon as the command is given.

If Success is returned in the command status, the procedure is terminated when either the upper layers issue a command to terminate the procedure by issuing the command terminate_procedure with the procedure code set to LimitedDiscovery or a timeout happens. When the procedure is terminated due to any of the above reasons, a ProcedureComplete event is returned with the procedure code set to LimitedDiscovery.

The device found when the procedure is ongoing is returned to the upper layers through the LeAdvertisingReport event.

Start the general discovery procedure. The controller is commanded to start active scanning.

Errors

Only underlying communication errors are reported.

Generated events

A command status event is generated as soon as the command is given.

If Success is returned in the command status, the procedure is terminated when either the upper layers issue a command to terminate the procedure by issuing the command terminate_procedure with the procedure code set to GeneralDiscovery or a timeout happens. When the procedure is terminated due to any of the above reasons, a ProcedureComplete event is returned with the procedure code set to GeneralDiscovery.

The device found when the procedure is ongoing is returned to the upper layers through the LeAdvertisingReport event.

Start the name discovery procedure.

A LE Create Connection call will be made to the controller by GAP with the initiator filter policy set to UseAddress, to "ignore whitelist and process connectable advertising packets only for the specified device". Once a connection is established, GATT procedure is started to read the device name characteristic. When the read is completed (successfully or unsuccessfully), a ProcedureComplete event is given to the upper layer. The event also contains the name of the device if the device name was read successfully.

Errors

Only underlying communication errors are reported.

Generated Events

A command status event is generated as soon as the command is given. If Success is returned, on completion of the procedure, a ProcedureComplete event is returned with the procedure code set to NameDiscovery.

Start the auto connection establishment procedure.

The devices specified are added to the white list of the controller and a le_create_connection call will be made to the controller by GAP with the initiator filter policy set to WhiteList, to "use whitelist to determine which advertiser to connect to". When a command is issued to terminate the procedure by upper layer, a le_create_connection_cancel call will be made to the controller by GAP.

Errors

  • If the white_list is too long (such that the serialized command would not fit in 255 bytes), a WhiteListTooLong is returned. The list cannot have more than 33 elements.

Start a general connection establishment procedure.

The host enables scanning in the controller with the scanner filter policy set to AcceptAll, to "accept all advertising packets" and from the scanning results, all the devices are sent to the upper layer using the event LE Advertising Report. The upper layer then has to select one of the devices to which it wants to connect by issuing the command create_connection. If privacy is enabled, then either a private resolvable address or a non-resolvable address, based on the address type specified in the command is set as the scanner address but the GAP create connection always uses a private resolvable address if the general connection establishment procedure is active.

Errors

Only underlying communication errors are reported.

Start a selective connection establishment procedure.

The GAP adds the specified device addresses into white list and enables scanning in the controller with the scanner filter policy set to WhiteList, to "accept packets only from devices in whitelist". All the devices found are sent to the upper layer by the event LE Advertising Report. The upper layer then has to select one of the devices to which it wants to connect by issuing the command create_connection.

Errors

  • If the white_list is too long (such that the serialized command would not fit in 255 bytes), a WhiteListTooLong is returned. The list cannot have more than 35 elements.

Start the direct connection establishment procedure.

A LE Create Connection call will be made to the controller by GAP with the initiator filter policy set to UseAddress to "ignore whitelist and process connectable advertising packets only for the specified device". The procedure can be terminated explicitly by the upper layer by issuing the command terminate_procedure. When a command is issued to terminate the procedure by upper layer, a le_create_connection_cancel call will be made to the controller by GAP.

Errors

Only underlying communication errors are reported.

Generated events

A command status event is generated as soon as the command is given. If Success is returned, on termination of the procedure, a LE Connection Complete event is returned. The procedure can be explicitly terminated by the upper layer by issuing the command terminate_procedure with the procedure_code set to DirectConnectionEstablishment.

The GAP procedure(s) specified is terminated.

Errors

  • NoProcedure if the bitfield is empty.
  • Underlying communication errors

Generated events

A command complete event is generated for this command. If the command was successfully processed, the status field will be Success and a ProcedureCompleted event is returned with the procedure code set to the corresponding procedure.

Start the connection update procedure.

A le_connection_update call is be made to the controller by GAP.

Errors

Only underlying communication errors are reported.

Generated events

A command status event is generated as soon as the command is given. If Success is returned, on completion of connection update, a LeConnectionUpdateComplete event is returned to the upper layer.

Send the SM pairing request to start a pairing process. The authentication requirements and I/O capabilities should be set before issuing this command using the set_io_capability and set_authentication_requirement commands.

Errors

Only underlying communication errors are reported.

Generated events

A command status event is generated when the command is received. If Success is returned in the command status event, a Pairing Complete event is returned after the pairing process is completed.

This command tries to resolve the address provided with the IRKs present in its database.

If the address is resolved successfully with any one of the IRKs present in the database, it returns success and also the corresponding public/static random address stored with the IRK in the database.

Errors

Only underlying communication errors are reported.

Generated events

A command complete event is generated. If Success is returned as the status, then the address is also returned in the event.

This command gets the list of the devices which are bonded. It returns the number of addresses and the corresponding address types and values.

Errors

Only underlying communication errors are reported.

Generated events

A command complete event is generated.

This command puts the device into broadcast mode.

Errors

Generated events

A command complete event is returned where the status indicates whether the command was successful.

Starts an Observation procedure, when the device is in Observer Role.

The host enables scanning in the controller. The advertising reports are sent to the upper layer using standard LE Advertising Report Event. See Bluetooth Core v4.1, Vol. 2, part E, Ch. 7.7.65.2, LE Advertising Report Event.

Errors

Only underlying communication errors are reported.

Generated events

A command complete event is generated.

The command finds whether the device, whose address is specified in the command, is bonded. If the device is using a resolvable private address and it has been bonded, then the command will return Success.

Errors

Only underlying communication errors are reported.

Generated events

A command complete event is generated.

Implementors