#include <bttypes.h>
| class TL2CapConfig |
API class for setting up an L2Cap channel configuration.
This class may be used to set all or a subset of the following configuration items: Channel Reliability (and associated timer) Maximum Transmission Unit (MTU) value preferred during MTU negotiation Maximum Receive Unit (MRU) value preferred during MRU negotiation Minimum MTU value acceptable during MTU negotiation Minimum MRU value acceptable during MRU negotiation Channel Priority
If a configuration item is to be set, then its 'Set' or 'Configure' method should be called.
Once a TL2CapConfig object has been set up it can be used to configure a socket using RSocket::SetOption or RSocket::Ioctl (or the CBluetoothSocket equivalents).
If the preferred Maximum Transmission Unit (MTU) value is specified but its minimum acceptable value is not specified in the same object, then the minimum acceptable value will be implicitly taken to be equal to the preferred MTU by the L2CAP APIs processing the object. This means that only an MTU greater than or equal to the preferred MTU will be accepted from the peer during negotiation.
If the Maximum Receive Unit (MRU) value is specified but its minimum acceptable value is not, then the minimum acceptable value is implicitly taken to be equal to the protocol minimum (48 bytes) by the L2CAP APIs processing the object.
Note that even though this API allows setting of Obsolescence timer, outgoing packet flushing may not be supported on all hardware.
See also: RSocket CBluetoothSocket
Used to indicate which config options have been specified by the user
Timer values in milliseconds for reliable and unreliable channels
| IMPORT_C | TL2CapConfig | ( | ) |
Constructor Start with no requests to update the required configuration.
| IMPORT_C TChannelPriority | ChannelPriority | ( | TBool & | aIsSpecified | ) | const |
Returns requested channel priority.
Also allows the user to know whether that priority has been set, or whether it is a random value that will be ignored. This is done via the parameter 'aIsSpecified'.
| Parameter | Description |
|---|---|
| aIsSpecified | Used to tell the caller whether the priority has been set. |
Returns: requested channel priority.
| IMPORT_C TChannelReliability | ChannelReliability | ( | TBool & | aIsSpecified, |
| TUint16 & | aAssociatedTimer | |||
| ) | const | |||
Returns the channel reliability and the associated timer.
Also allows the user to know whether reliability has been set up, or whether it is a random value that will be ignored. This is done via the parameter 'aIsSpecified'. The associated timer is the obsolescence timer if the channel is unreliable and the retransmission timer if it is reliable. This is returned via the parameter 'aAssociatedTimer'. Note that if ConfigureUnreliableDesiredChannel was used then both timer values have been set and this method will only return the obsolescence timeout. The overload of this method which doesn't return a timer value together with the timer value getters can be used instead of this one to uniformly handle all cases.
| Parameter | Description |
|---|---|
| aIsSpecified | Used to tell the caller whether reliability has been set up. |
| aAssociatedTimer | This is a 'return' value. The associated timer is the obsolescence timer if the channel is unreliable and the retransmission timer if it is reliable. |
Returns: the reliability
| IMPORT_C TChannelReliability | ChannelReliability | ( | TBool & | aIsSpecified | ) | const |
Returns the channel reliability.
Also allows the user to know whether reliability has been set up, or whether it is a random value that will be ignored. This is done via the parameter 'aIsSpecified'. The associated timer is the obsolescence timer if the channel is unreliable, the retransmission timer if it is reliable, and both timers if it's 'unreliable desired'. The associated timer values can be obtained with RetransmissionTimer() and ObsolescenceTimer() methods.
| Parameter | Description |
|---|---|
| aIsSpecified | Used to tell the caller whether reliability has been set up. |
Returns: the reliability
| IMPORT_C TInt | ConfigureChannelPriority | ( | TChannelPriority | aPriority | ) |
Request a new channel priority.
L2Cap channels have three priorities, low, medium, and high. Data on channels with higher priority may be sent before data on channels with lower priority.
| Parameter | Description |
|---|---|
| aPriority | the priority to be used for this L2Cap channel |
Returns: error code, currently KErrNone
Request a reliable channel.
A reliable channel relies on the retransmission by L2Cap of unacknowledged L2Cap packets. Retransmissions are continued for a specified length of time. If this time is exceeded the L2Cap channel is disconnected.
The resulting behaviour depends on the setting of the LegacyModesDisallowed option (
See also: SetLegacyModesDisallowed). If that option is disabled (which is the default setting), then the channel mode attempted in L2CAP configuration process will be Enhanced Retransmission Mode if the peer supports it, else Retransmission Mode if the peer supports it, else Basic Mode.
If the LegacyModesDisallowed option is enabled, then the connection will only be made if the peer supports and accepts the Enhanced Retransmission Mode. If it doesn't then the connection will not be made.
Note that due to the nature of the negotiation process, it is not guranteed that a mode will be negotiated even if it's supported by a peer.
The KL2CAPNegotiatedChannelMode socket option can be used to obtain the negotiated channel mode after a socket has been connected.
| Parameter | Description |
|---|---|
| aRetransmissionTimer | The length of time allowed for l2Cap transmissions. Note that the value of this parameter does not directly drive the L2CAP retransmission timer. It is instead translated into a corresponding value for the maximum number of transmissions of a single packet. If that number is exceeded, then the connection is closed. |
Returns: error code, currently KErrNone
Request an unreliable channel.
An unreliable channel allows L2Cap packets to be dropped by the baseband. It helps to maintain low latency at the cost of reliability.
The resulting behaviour depends on the setting of the LegacyModesDisallowed option (
See also: SetLegacyModesDisallowed). If that option is disabled (which is the default setting), then the channel mode attempted in L2CAP configuration process will be Streaming Mode if the peer supports it, else Flow Control Mode if the peer supports it, else Basic Mode.
If the LegacyModesDisallowed option is enabled, then the connection will only be made if the peer supports and accepts Streaming Mode. If it doesn't then the connection will not be made.
Note that due to the nature of the negotiation process, it is not guranteed that a mode will be negotiated even if it's supported by a peer.
The KL2CAPNegotiatedChannelMode socket option can be used to obtain the negotiated channel modes after a socket has been connected.
| Parameter | Description |
|---|---|
| aObsolescenceTimer | The time after which a packet may be dropped or "flushed" by the baseband. Note that outgoing packet flushing may not be implemented on all Symbian OS platforms. |
Returns: error code, KErrArgument if the obsolescence time is made shorter than is physically possible, otherwise KErrNone
| IMPORT_C TInt | ConfigureUnreliableDesiredChannel | ( | TUint16 | aObsolescenceTimer, |
| TUint16 | aRetransmissionTimer | |||
| ) | ||||
Request an unreliable channel, but allow any channel mode to be negotiated.
This will configure the socket to prefer unreliable modes during L2CAP channel configuration, but accept any mode proposed by the peer. The purpose of this interface is to be used with listening sockets which need to accept both reliable and unreliable mode connections on a single PSM. The ConfigureReliableChannel and ConfigureUnreliableChannel methods should be used in preference to this one in normal situations.
The LegacyModesDisallowed option does not influence the behavior of this method.
The KL2CAPNegotiatedChannelMode socket option can be used to obtain the negotiated channel modes after a socket has been connected.
| Parameter | Description |
|---|---|
| aObsolescenceTimer | The time after which a packet may be dropped or "flushed" by the baseband if an Unreliable channel is negotiated. Note that outgoing packet flushing may not be implemented on all Symbian OS platforms. |
| aRetransmissionTimer | The length of time allowed for l2Cap transmissions if a Reliable channel is negotiated. Note that the value of this parameter does not directly drive the L2CAP retransmission timer. It is instead translated into a corresponding value for the maximum number of transmissions of a single packet. If that number is exceeded, then the connection is closed. |
Returns: error code, KErrArgument if the obsolescence time is made shorter than is physically possible, otherwise KErrNone
| IMPORT_C TBool | LegacyModesDisallowed | ( | ) | const |
Checks if the usage of legacy L2CAP channel modes is disallowed. The default value is to allow the usage of legacy modes.
Returns preferred MRU.
Also allows the user to know whether that value has been set, or whether it is a random value that will be ignored. This is done via the parameter 'aIsSpecified'.
| Parameter | Description |
|---|---|
| aIsSpecified | Used to tell the caller whether the MRU value has been set. |
Returns: preferred MRU
Returns preferred MTU.
Also allows the user to know whether that value has been set, or whether it is a random value that will be ignored. This is done via the parameter 'aIsSpecified'.
| Parameter | Description |
|---|---|
| aIsSpecified | Used to tell the caller whether the MTU value has been set. |
Returns: preferred MTU
Returns the minimum acceptable negotiated MRU.
Also allows the user to know whether that value has been set, or whether it is a random value that will be ignored. This is done via the parameter 'aIsSpecified'.
| Parameter | Description |
|---|---|
| aIsSpecified | Used to tell the caller whether the smallest acceptable MRU value has been set. |
Returns: Requested smallest acceptable MRU.
Returns the minimum acceptable negotiated MTU.
Also allows the user to know whether that value has been set, or whether it is a random value that will be ignored. This is done via the parameter 'aIsSpecified'.
| Parameter | Description |
|---|---|
| aIsSpecified | Used to tell the caller whether the smallest acceptable MTU value has been set. |
Returns: Requested smallest acceptable MTU.
| IMPORT_C TInt | SetChannelPriority | ( | TChannelPriority | aPriority = ELow | ) |
DeprecatedUse ConfigureChannelPriority(TChannelPriority aPriority) instead
Request a new channel priority.
L2Cap channels have three priorities, low, medium, and high. Data on channels with higher priority may be sent before data on channels with lower priority.
DeprecatedUse ConfigureChannelPriority(TChannelPriority aPriority) instead
| Parameter | Description |
|---|---|
| aPriority | the priority to be used for this L2Cap channel |
Returns: error code, currently KErrNone
| IMPORT_C void | SetLegacyModesDisallowed | ( | TBool | aDisallowed | ) |
Disallow usage of legacy L2CAP channel modes.
This option influences the behavior of ConfigureReliableChannel and ConfigureUnreliableChannel. If it's enabled, then only the newest reliable/unreliable modes will be allowed during L2CAP channel configuration.
The default value is to allow the usage of legacy modes.
| Parameter | Description |
|---|---|
| aDisallowed | Whether the usage of legacy modes is disallowed. |
Request a new preferred Max Receive Unit size.
The L2CAP channel configuration process will attempt to configure with this MRU size. The resulting negotiated MRU will be at most this size and at least the size given by the minimum acceptable MRU option (
See also: SetMinMRU). Please note that if the minimum acceptable MRU is not specified, it is taken by APIs using this class to be equal to the protocol minimum (48 bytes).
| Parameter | Description |
|---|---|
| aSize | the MRU size for use in configuration |
Returns: error code, KErrArgument if MRU set too small, otherwise KErrNone
Request a new preferred Max Transmit Unit size.
The L2CAP channel configuration process will attempt to configure with this MTU size. The resulting negotiated MTU will be at most this size and at least the size given by the minimum acceptable MTU option (
See also: SetMinMTU). Please note that if the minimum acceptable MTU is not specified along with this parameter, it is taken to be equal to the preferred value, so a smaller MTU value will not be accepted from the peer during the negotiation.
| Parameter | Description |
|---|---|
| aSize | the MTU size for use in configuration |
Returns: error code, KErrArgument if MTU set too small, otherwise KErrNone
Set the minimum MRU acceptable during L2CAP channel configuration.
The configuration process will attempt to configure with the largest possible MRU that's greater than or equal to this boundary and less than or equal to the preferred value (
See also: SetMaxReceiveUnitSize) or the preferred stack default.
If the peer proposes an MRU below the minimum the L2CAP channel will be disconnected, so this option should not be specified unless the application/profile requires a guarantee of MRU of certain size and can not work with a smaller one.
| Parameter | Description |
|---|---|
| aSize | the smallest acceptable MRU size |
Returns: error code, KErrArgument if MRU set too small, otherwise KErrNone
Set the minimum MTU acceptable during L2CAP channel configuration.
The configuration process will attempt to configure with the largest possible MTU that's greater than or equal to this boundary and less than or equal to the preferred value (
See also: SetMaxTransmitUnitSize) or the preferred stack default.
A peer's proposal of any value below the minimum will be rejected and replied to with a value equal to the acceptable minimum. The peer will then choose to either close the connection or proceed with the acceptable minimum.
| Parameter | Description |
|---|---|
| aSize | the smallest acceptable MTU size |
Returns: error code, KErrArgument if MTU set too small, otherwise KErrNone
DeprecatedUse ConfigureReliableChannel(TUint16 aRetransmissionTimer) instead
Request a reliable channel.
This is a deprecated version of the ConfigureReliableChannel method and its behaviour is exactly the same.
DeprecatedUse ConfigureReliableChannel(TUint16 aRetransmissionTimer) instead
| Parameter | Description |
|---|---|
| aRetransmissionTimer | The length of time allowed for l2Cap transmissions |
Returns: error code, currently KErrNone
DeprecatedUse ConfigureUnreliableChannel(TUint16 aObsolescenceTimer) instead
Request an unreliable channel.
This is a deprecated version of the ConfigureReliableChannel method and its behaviour is exactly the same.
DeprecatedUse ConfigureUnreliableChannel(TUint16 aObsolescenceTimer) instead
| Parameter | Description |
|---|---|
| aObsolescenceTimer | The time after which a packet may be dropped or "flushed" by the baseband. |
Returns: error code, KErrArgument if the obsolescence time is made shorter than is physically possible, otherwise KErrNone