| 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.
| Public Member Enumerations | |
|---|---|
| enum | TChannelPriority { EHigh = 2, EMedium = 1, ELow = 0 } |
| enum | TChannelReliability { EReliableChannel, EUnreliableChannel, EUnreliableDesiredChannel } |
| enum | TL2CapConfigSpecifiedMask { ENoConfigElementsSpecified = 0x0000, EMTUSizeSpecifiedMask = 0x0001, EMRUSizeSpecifiedMask = 0x0002, EReliabilitySpecifiedMask = 0x0004, EPrioritySpecifiedMask = 0x0008, EMinMTUSizeSpecifiedMask = 0x0010, EMinMRUSizeSpecifiedMask = 0x0020, ELegacyModesDisallowedSpecifiedMask = 0x0040 } |
| enum | TL2CapConfigSpecifiedTimers { EDefaultRetransmission = 0xffff, EMinDataObsolescenceTimeout = 0x0a, EDefaultDataObsolescenceTimeout = 0xffff } |
| 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'.
| TBool & aIsSpecified | Used to tell the caller whether the priority has been set. |
| 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.
| 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.
| TBool & aIsSpecified | Used to tell the caller whether reliability has been set up. |
| 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.
| TChannelPriority aPriority | the priority to be used for this L2Cap channel |
| IMPORT_C TInt | ConfigureReliableChannel | ( | TUint16 | aRetransmissionTimer | ) |
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 (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.
| TUint16 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. |
| IMPORT_C TInt | ConfigureUnreliableChannel | ( | TUint16 | aObsolescenceTimer | ) |
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 (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.
| TUint16 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. |
| 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.
| TUint16 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. |
| TUint16 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. |
| 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.
| IMPORT_C TUint16 | MaxReceiveUnitSize | ( | TBool & | aIsSpecified | ) | const |
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'.
| TBool & aIsSpecified | Used to tell the caller whether the MRU value has been set. |
| IMPORT_C TUint16 | MaxTransmitUnitSize | ( | TBool & | aIsSpecified | ) | const |
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'.
| TBool & aIsSpecified | Used to tell the caller whether the MTU value has been set. |
| IMPORT_C TUint16 | MinMRU | ( | TBool & | aIsSpecified | ) | const |
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'.
| TBool & aIsSpecified | Used to tell the caller whether the smallest acceptable MRU value has been set. |
| IMPORT_C TUint16 | MinMTU | ( | TBool & | aIsSpecified | ) | const |
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'.
| TBool & aIsSpecified | Used to tell the caller whether the smallest acceptable MTU value has been set. |
| IMPORT_C TUint16 | ObsolescenceTimer | ( | TBool & | aIsSpecified | ) | const |
Returns the obsolescence timer.
| TBool & aIsSpecified | Used to tell the caller whether the timer value has been set. |
| IMPORT_C TUint16 | RetransmissionTimer | ( | TBool & | aIsSpecified | ) | const |
Returns the retransmission timer.
| TBool & aIsSpecified | Used to tell the caller whether the timer value has been set. |
| IMPORT_C TInt | SetChannelPriority | ( | TChannelPriority | aPriority = ELow | ) |
Use 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.
Use ConfigureChannelPriority(TChannelPriority aPriority) instead
| TChannelPriority aPriority = ELow | the priority to be used for this L2Cap channel |
| 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.
| TBool aDisallowed | Whether the usage of legacy modes is disallowed. |
| IMPORT_C TInt | SetMaxReceiveUnitSize | ( | TUint16 | aSize = 0xffff | ) |
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 (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).
| TUint16 aSize = 0xffff | the MRU size for use in configuration |
| IMPORT_C TInt | SetMaxTransmitUnitSize | ( | TUint16 | aSize = 0xffff | ) |
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 (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.
| TUint16 aSize = 0xffff | the MTU size for use in configuration |
| IMPORT_C TInt | SetMinMRU | ( | TUint16 | aSize | ) |
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 (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.
| TUint16 aSize | the smallest acceptable MRU size |
| IMPORT_C TInt | SetMinMTU | ( | TUint16 | aSize | ) |
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 (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.
| TUint16 aSize | the smallest acceptable MTU size |
| IMPORT_C TInt | SetupReliableChannel | ( | TUint16 | aRetransmissionTimer = EDefaultRetransmission | ) |
Use ConfigureReliableChannel(TUint16 aRetransmissionTimer) instead
Request a reliable channel.
This is a deprecated version of the ConfigureReliableChannel method and its behaviour is exactly the same.
Use ConfigureReliableChannel(TUint16 aRetransmissionTimer) instead
| TUint16 aRetransmissionTimer = EDefaultRetransmission | The length of time allowed for l2Cap transmissions |
| IMPORT_C TInt | SetupUnreliableChannel | ( | TUint16 | aObsolescenceTimer = EDefaultDataObsolescenceTimeout | ) |
Use ConfigureUnreliableChannel(TUint16 aObsolescenceTimer) instead
Request an unreliable channel.
This is a deprecated version of the ConfigureReliableChannel method and its behaviour is exactly the same.
Use ConfigureUnreliableChannel(TUint16 aObsolescenceTimer) instead
| TUint16 aObsolescenceTimer = EDefaultDataObsolescenceTimeout | The time after which a packet may be dropped or "flushed" by the baseband. |
Priority required for data on L2Cap channel
| EHigh = 2 | |
| EMedium = 1 | |
| ELow = 0 |
Reliability of data transfer preferred for L2Cap channel.
| EReliableChannel | |
| EUnreliableChannel | |
| EUnreliableDesiredChannel |
Used to indicate which config options have been specified by the user
| ENoConfigElementsSpecified = 0x0000 | |
| EMTUSizeSpecifiedMask = 0x0001 | |
| EMRUSizeSpecifiedMask = 0x0002 | |
| EReliabilitySpecifiedMask = 0x0004 | |
| EPrioritySpecifiedMask = 0x0008 | |
| EMinMTUSizeSpecifiedMask = 0x0010 | |
| EMinMRUSizeSpecifiedMask = 0x0020 | |
| ELegacyModesDisallowedSpecifiedMask = 0x0040 |
Timer values in milliseconds for reliable and unreliable channels
| EDefaultRetransmission = 0xffff |
This is a time in milliseconds. However 0xffff has been given a special meaning in this interface. It means "Allow maximum possible number of transmissions of a single packet before giving up and disconnecting the L2Cap channel." This is the maximum number of transmissions effectively allowed by the spec. It only applies to reliable modes and is 255 for Retransmission Mode and Infinity for Enhanced Retransmission Mode. |
| EMinDataObsolescenceTimeout = 0x0a |
Minimum data obsolescence timeout required because data packets will not ever be sent if we flush them too quickly. Speed of sending data depends on how many channels are open and channel priority. Note that flushing of outgoing packets may not be implemented on all Symbian OS platforms. |
| EDefaultDataObsolescenceTimeout = 0xffff |
This is translated to mean never flush (as per spec). |
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.