Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: bt_sock.h
Link against: bluetooth.lib

Class CBluetoothSocket

class CBluetoothSocket : public CBase;

Description

This allows Bluetooth ACL socket-based services to be run.

It allows all user-plane data flow to occur, plus control-plane Bluetooth baseband modification capabilities.

For a more detailed description of RBTBaseband functionality see the class and function documentation for RBTPhysicalLinkAdapter.

This class doesn't provide the functionality to directly activate Active mode (this is implementated in class RBTPhysicalLinkAdapter.)

Derivation

Members

Defined in CBluetoothSocket:
Accept(), Accept(), ActivateBasebandEventNotifier(), ActivateParkRequester(), ActivateSniffRequester(), AllowLowPowerModes(), AllowRoleSwitch(), AsyncDelete(), AutomaticSniffMode(), Bind(), CancelAccept(), CancelAll(), CancelBasebandEventNotifier(), CancelConnect(), CancelIoctl(), CancelLowPowerModeRequester(), CancelRead(), CancelRecv(), CancelSend(), CancelWrite(), Connect(), Connect(), Connect(), GetDisconnectData(), GetOpt(), GetOpt(), Info(), Ioctl(), Ioctl(), Listen(), Listen(), Listen(), LocalName(), LocalPort(), Name(), NewL(), NewL(), NewL(), NewL(), NewL(), NewLC(), NewLC(), NewLC(), NewLC(), NewLC(), PhysicalLinkState(), PreventLowPowerModes(), PreventRoleSwitch(), Read(), Recv(), Recv(), RecvFrom(), RecvFrom(), RecvOneOrMore(), RemoteName(), RequestChangeSupportedPacketTypes(), RequestMasterRole(), RequestSlaveRole(), Send(), Send(), SendTo(), SendTo(), SetAutomaticSniffMode(), SetAutomaticSniffMode(), SetLocalPort(), SetNotifier(), SetOpt(), SetOpt(), SetOption(), Shutdown(), Shutdown(), Transfer(), Write(), ~CBluetoothSocket()

Inherited from CBase:
Delete(), Extension_(), operator new()

See also:


Construction and destruction


NewL()

Capability: LocalServices

static IMPORT_C CBluetoothSocket *NewL(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer, TUint aSockType, TUint aProtocol);

Pre-Condition

A session on the socket server has been started.

Description

Standard Bluetooth socket NewL constructor.

Opens a Bluetooth socket. The constructor identifies the server, socket type, and bluetooth protocol to be used for the socket, as well as an asynchronous notifier.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock).

TUint aSockType

One of a set of values defined in es_sock.h, for example KSockStream.

TUint aProtocol

An entry point into the Bluetooth stack, for example KL2CAP.

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.

Leave codes

No

memory, or error on opening socket.


NewLC()

Capability: LocalServices

static IMPORT_C CBluetoothSocket *NewLC(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer, TUint aSockType, TUint aProtocol);

Description

Standard Bluetooth socket NewLC constructor.

Opens a Bluetooth socket as with the NewL() above, but leaves the returned CBluetoothSocket object on the cleanup stack.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

TUint aSockType

One of a set of values defined in es_sock.h, for example KSockStream

TUint aProtocol

An entry point into the Bluetooth stack, for example KL2CAP

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.


NewL()

Capability: LocalServices

static IMPORT_C CBluetoothSocket *NewL(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer, TUint aSockType, TUint aProtocol, RConnection &aConnection);

Pre-Condition

A session on the socket server has been started.

Description

Opens a Bluetooth socket on a specified connection.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

TUint aSockType

One of a set of values defined in es_sock.h, for example KSockStream

TUint aProtocol

An entry point into the Bluetooth stack, for example KL2CAP

RConnection &aConnection

A socket server management interface for a connection

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.

Leave codes

No

memory, or error on opening socket


NewLC()

Capability: LocalServices

static IMPORT_C CBluetoothSocket *NewLC(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer, TUint aSockType, TUint aProtocol, RConnection &aConnection);

Description

This constructor opens a Bluetooth socket on a specified connection.

Leaves the socket on the cleanup stack.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

TUint aSockType

One of a set of values defined in es_sock.h, for example KSockStream

TUint aProtocol

An entry point into the Bluetooth stack, for example KL2CAP

RConnection &aConnection

A socket server management interface for a connection

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.


NewL()

Capability: LocalServices

static IMPORT_C CBluetoothSocket *NewL(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer, const TDesC &aName);

Pre-Condition

A session on the socket server has been started.

Description

Bluetooth socket named protocol NewL() constructor.

Opens a Bluetooth socket over a specified named protocol, such as "L2CAP".

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

const TDesC &aName

A descriptor containing the name of the protocol wanted for making a Bluetooth connection, for example _L("L2CAP")

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.

Leave codes

No

memory, or error on opening socket


NewLC()

Capability: LocalServices

static IMPORT_C CBluetoothSocket *NewLC(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer, const TDesC &aName);

Description

Bluetooth socket named protocol NewLC() constructor.

Opens a Bluetooth socket over a specified named protocol, such as "L2CAP". Leaves returned CBluetoothSocket object on the cleanup stack.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

const TDesC &aName

A descriptor containing the name of the protocol wanted for making a Bluetooth connection, for example _L("L2CAP")

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.


NewL()

static IMPORT_C CBluetoothSocket *NewL(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer);

Pre-Condition

A session on the socket server has been started.

Description

Bluetooth blank socket NewL() constructor.

Opens a blank socket to be used when accepting an incoming connection. This socket should be used as the parameter when a listening socket calls CBluetoothSocket::Accept(CBluetoothSocket& aBlankSocket). When that connection completes this blank socket becomes the Bluetooth socket for that connection.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.

Leave codes

No

memory, or error on opening socket


NewLC()

static IMPORT_C CBluetoothSocket *NewLC(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer);

Pre-Condition

A session on the socket server has been started.

Description

Bluetooth blank socket NewLC() constructor

Opens a blank socket to be used when accepting an incoming connection. This socket should be used as the parameter when a listening socket calls CBluetoothSocket::Accept(CBluetoothSocket& aBlankSocket). When that connection completes this blank socket becomes the Bluetooth socket for that connection.

Leaves returned CBluetoothSocket object on the cleanup stack.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.

Leave codes

No

memory, or error on opening socket


NewL()

static IMPORT_C CBluetoothSocket *NewL(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer, RSocket &aSocket);

Pre-Condition

A session on the socket server has been started, and aSocket is open and is set as "Transferable" through the KSOEnableTransfer SetOpt.

Description

Bluetooth socket using an existing RSocket instance constructor.

Takes ownership of an existing socket to be used as the underlying connection for this Socket wrapper. This should be used where an existing API returned a RSocket representing a Bluetooth connection.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

RSocket &aSocket

A handle to an existing socket.

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.

Leave codes

No

memory


NewLC()

static IMPORT_C CBluetoothSocket *NewLC(MBluetoothSocketNotifier &aNotifier, RSocketServ &aServer, RSocket &aSocket);

Pre-Condition

A session on the socket server has been started, and aSocket is open and is set as "Transferable" through the KSOEnableTransfer SetOpt.

Description

Bluetooth socket using an existing RSocket instance constructor.

Takes ownership of an existing socket to be used as the underlying connection for this Socket wrapper. This should be used where an existing API returned a RSocket representing a Bluetooth connection.

Leaves returned CBluetoothSocket object on the cleanup stack.

Parameters

MBluetoothSocketNotifier &aNotifier

The object which will receive asynchronous events.

RSocketServ &aServer

A handle to an existing session on the socket server (ESock)

RSocket &aSocket

A handle to an existing socket.

Return value

CBluetoothSocket *

The Bluetooth socket created with the constructor.

Leave codes

No

memory


~CBluetoothSocket()

IMPORT_C ~CBluetoothSocket();

Description

Destructor

Cancels any outstanding Bluetooth socket functions and closes the socket. Note sockets should be closed or shutdown before destructor is called.

[Top]


Member functions


Send()

IMPORT_C TInt Send(const TDesC8 &aDesc, TUint someFlags);

Description

Sends data to a remote bluetooth device.

The Send() operation checks that another Send() operation isn't already in progress before sending.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleSendCompleteL(TInt aErr).

If Automatic Sniff Mode is active, using this function will not automatically put the link into active mode. If it is required that the link be taken out of sniff mode automatically when data is to be sent then the CBluetoothSocket::Write(const TDesC8& aDesc) function should be used instead.

Parameters

const TDesC8 &aDesc

A descriptor for the data being sent to the remote device.

TUint someFlags

Bluetooth specific flags.

Return value

TInt

KErrNone meaning the operation was successful and data is being sent to the remote device, or KErrInUse meaning a previous Send() is not yet finished.


Send()

IMPORT_C TInt Send(const TDesC8 &aDesc, TUint someFlags, TSockXfrLength &aLen);

Description

Sends data to a remote bluetooth device.

The Send() operation checks that another Send() operation isn't already in progress before sending.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleSendCompleteL(TInt aErr)

If Automatic Sniff Mode is active, using this function will not automatically put the link into active mode. If it is required that the link be taken out of sniff mode automatically when data is to be sent then the CBluetoothSocket::Write(const TDesC8& aDesc) function should be used instead.

Parameters

const TDesC8 &aDesc

A descriptor for the data being sent to the remote device.

TUint someFlags

Bluetooth specific flags.

TSockXfrLength &aLen

Amount of data being sent.

Return value

TInt

KErrNone meaning the operation was successful and data is being sent to the remote device, or KErrInUse meaning a previous Send() is not yet finished.


CancelSend()

IMPORT_C void CancelSend();

Description

Cancels an outstanding Bluetooth Send() operation.

Calling the function will cause an outstanding Bluetooth Send() operation to complete prematurely.

See also:


Recv()

IMPORT_C TInt Recv(TDes8 &aDesc, TUint flags);

Description

Receives data from a remote Bluetooth device.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleReceiveCompleteL(TInt aErr)

Parameters

TDes8 &aDesc

A descriptor for the information being sent to the remote Bluetooth device.

TUint flags

Bluetooth information flags.

Return value

TInt

KErrNone meaning the operation was successful and data is being received from the remote device, or KErrInUse meaning a previous Recv() is not yet finished.


Recv()

IMPORT_C TInt Recv(TDes8 &aDesc, TUint flags, TSockXfrLength &aLen);

Description

Receives data from a remote Bluetooth device.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleReceiveCompleteL(TInt aErr)

Parameters

TDes8 &aDesc

A descriptor for the information being sent to the remote Bluetooth device.

TUint flags

Bluetooth information flags.

TSockXfrLength &aLen

A length indicating how much data was read. This is the same as length of the returned aDesc.

Return value

TInt

KErrNone meaning the operation was successful and data is being received from the remote device, or KErrInUse meaning a previous Recv() is not yet finished.


RecvOneOrMore()

IMPORT_C TInt RecvOneOrMore(TDes8 &aDesc, TUint flags, TSockXfrLength &aLen);

Description

Receives data from a remote Bluetooth device, completing when data is available.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleReceiveCompleteL(TInt aErr).

Parameters

TDes8 &aDesc

A descriptor for the information being sent to the remote Bluetooth device.

TUint flags

Bluetooth information flags.

TSockXfrLength &aLen

A length indicating how much data was read. This is the same as length of the returned aDesc.

Return value

TInt

KErrNone meaning the operation was successful and data is being received from the remote device, or KErrInUse meaning a previous Recv() is not yet finished.


CancelRecv()

IMPORT_C void CancelRecv();

Description

Cancels an outstanding Recv() operation.

Calling this function will cause any outstanding receive operation to cancel.

See also:


Read()

IMPORT_C TInt Read(TDes8 &aDesc);

Description

Receives data from a remote Bluetooth host.

Read() is only used with a connected Bluetooth host.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleReceiveCompleteL(TInt aErr)

Parameters

TDes8 &aDesc

A descriptor for the data being read.

Return value

TInt

KErrNone meaning the operation was successful and data is being received from the remote device, or KErrInUse meaning a previous Recv() is not yet finished.


CancelRead()

IMPORT_C void CancelRead();

Description

Cancels an outstanding Read() operation.

Calling this function will cause any outstanding Read() operation to cancel.

See also:


Write()

IMPORT_C TInt Write(const TDesC8 &aDesc);

Description

Writes to a remote Bluetooth device

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleSendCompleteL(TInt aErr)

If Automatic Sniff Mode is active on this socket instance, then upon calling this function the link will be put into active mode. If no CBluetoothSocket::Write() calls are made for a period of the timeout specified during activation of the automatic sniffing then the link will be put back into sniff mode.

Parameters

const TDesC8 &aDesc

A descriptor for the data being sent to the remote Bluetooth device.

Return value

TInt

KErrNone meaning the operation was successful and data is being sent to the remote device, or KErrInUse meaning a previous Write() is not yet finished.


CancelWrite()

IMPORT_C void CancelWrite();

Description

Cancels an outstanding Write() operation.

Calling this operation will cause any outstanding Write() operation to cancel.

See also:


SendTo()

IMPORT_C TInt SendTo(const TDesC8 &aDesc, TSockAddr &aSockAddr, TUint flags);

Description

Sends the aDesc data to the aAddr specified and applies the flags indicated to the operation.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleSendCompleteL(TInt aErr)

If Automatic Sniff Mode is active, using this function will not automatically put the link into active mode. If it is required that the link be taken out of sniff mode automatically when data is to be sent then the CBluetoothSocket::Write(const TDesC8& aDesc) function should be used instead.

Parameters

const TDesC8 &aDesc

A descriptor for the data being sent.

TSockAddr &aSockAddr

The address of the Bluetooth device.

TUint flags

The Bluetooth flags.

Return value

TInt

KErrNone meaning the operation was successful and data is being sent to the specified and addressed remote device, or KErrInUse meaning a previous SendTo() is not yet finished.


SendTo()

IMPORT_C TInt SendTo(const TDesC8 &aDesc, TSockAddr &aSockAddr, TUint flags, TSockXfrLength &aLen);

Description

Sends the aDesc data to the aAddr specified and applies the flags indicated to the operation.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleSendCompleteL(TInt aErr)

If Automatic Sniff Mode is active, using this function will not automatically put the link into active mode. If it is required that the link be taken out of sniff mode automatically when data is to be sent then the CBluetoothSocket::Write(const TDesC8& aDesc) function should be used instead.

Parameters

const TDesC8 &aDesc

A descriptor for the data being sent.

TSockAddr &aSockAddr

The address of the Bluetooth device.

TUint flags

The Bluetooth flags.

TSockXfrLength &aLen

An integer representing the length of the message.

Return value

TInt

KErrNone meaning the operation was successful and data is being sent to the specified and addressed remote device, or KErrInUse meaning a previous SendTo() is not yet finished.


RecvFrom()

IMPORT_C TInt RecvFrom(TDes8 &aDesc, TSockAddr &aSockAddr, TUint flags);

Description

Receives aDesc data from the named remote aAddr Bluetooth device using the flags indicated.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleReceiveCompleteL(TInt aErr)

Parameters

TDes8 &aDesc

A descriptor for the data being received.

TSockAddr &aSockAddr

The address of the Bluetooth device.

TUint flags

The Bluetooth flags.

Return value

TInt

KErrNone meaning the operation was successful and data is being received from the specified and addressed remote device, or KErrInUse meaning a previous RecvFrom() is not yet finished.


RecvFrom()

IMPORT_C TInt RecvFrom(TDes8 &aDesc, TSockAddr &aSockAddr, TUint flags, TSockXfrLength &aLen);

Description

Receives aDesc data from the named remote aAddr Bluetooth device using the flags indicated.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleReceiveCompleteL(TInt aErr)

Parameters

TDes8 &aDesc

A descriptor for the data being received.

TSockAddr &aSockAddr

The address of the Bluetooth device.

TUint flags

The Bluetooth flags.

TSockXfrLength &aLen

An integer representing the length of the message.

Return value

TInt

KErrNone meaning the operation was successful and data is being received from the specified and addressed remote device, or KErrInUse meaning a previous RecvFrom() is not yet finished.


Connect()

IMPORT_C TInt Connect(TBTSockAddr &aSockAddr);

Description

Opens a connection to a specific Bluetooth device by its address.

The address represents the address of the remote Bluetooth device. A socket may only have one connect operation outstanding at any one time. Once the connect is completed, the socket is ready to send or receive data. If a socket is unbound - i.e. Bind() has not been called yet - then it will automatically have a local address allocated.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleConnectCompleteL(TInt aErr)

Parameters

TBTSockAddr &aSockAddr

The address of the bluetooth device to which the connection is being made.

Return value

TInt

KErrInUse if the device is already being used, else KErrNone is the connection is successful.


Connect()

IMPORT_C TInt Connect(TBTSockAddr &aSockAddr, const TDesC8 &aConnectDataOut, TDes8 &aConnectDataIn);

Description

Connects to a remote Bluetooth device by address with a defined data-out and data-in descriptor.

The address provided specifies the address of the remote Bluetooth host. Data can be sent in connect request packets, which may be provided in the data-out descriptor, or connect responses, which may be collected in the data-in descriptor.

A socket may only have one connect operation outstanding at any one time. Once the connect is completed, the socket is ready to send or receive data. If a socket is unbound - i.e. Bind() has not been called yet - then it will automatically have a local address allocated.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleConnectCompleteL(TInt aErr).

Parameters

TBTSockAddr &aSockAddr

The address of the remote Bluetooth device.

const TDesC8 &aConnectDataOut

A descriptor containing data to be sent.

TDes8 &aConnectDataIn

A descriptor to receive data.

Return value

TInt

KErrInUse if the device is already being used, else KErrNone is the connection is successful.


Connect()

IMPORT_C TInt Connect(TBTSockAddr &aAddr, TUint16 aServiceBits);

Description

Sets the Service bits in the Class Of Device. If this is successful, the socket then opens a connection to a specific Bluetooth device by its address.

The address represents the address of the remote Bluetooth device. A socket may only have one connect operation outstanding at any one time. Once the connect is completed, the socket is ready to send or receive data. If a socket is unbound - i.e. Bind() has not been called yet - then it will automatically have a local address allocated.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleConnectCompleteL(TInt aErr)

Parameters

TBTSockAddr &aAddr

The address of the bluetooth device to which the connection is being made.

TUint16 aServiceBits

Return value

TInt

KErrInUse if the device is already being used, else KErrNone is the connection is successful.


CancelConnect()

IMPORT_C void CancelConnect();

Description

Cancel an attempted connection.

See also:


Bind()

IMPORT_C TInt Bind(TSockAddr &aSockAddr);

Description

Sets a Bluetooth socket address.

Sets the local address of a socket. When a socket is opened it has no name associated with it, and binding is required so data can be routed to the socket. Bind() should be called before Listen() or Connect().

Parameters

TSockAddr &aSockAddr

The address of the socket.

Return value

TInt

aAddr The address of the socket.


SetLocalPort()

IMPORT_C TInt SetLocalPort(TInt aPort);

Description

Sets the local port of a Bluetooth socket.

Setting the local port is equivalent to calling Bind() with only the port set in the address.

Parameters

TInt aPort

The socket port.

Return value

TInt

aPort The socket port.


Accept()

IMPORT_C TInt Accept(CBluetoothSocket &aBlankSocket);

Description

Accepts a connection from a remote Bluetooth socket.

The call extracts the first pending connection on a queue of sockets, the queue size being previously specified by Listen(). On successful completion the blank socket is given the handle of the new socket and it may then be used to transfer data. After completion the accept socket may be used to make further connections with new blank sockets (see Open() on how to open a blank socket).

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleAcceptCompleteL(TInt aErr)

Parameters

CBluetoothSocket &aBlankSocket

A socket opened as a blank socket.

Return value

TInt

KErrNone if the connection is established. KErrInUse if a connection already exists.


Accept()

IMPORT_C TInt Accept(CBluetoothSocket &aBlankSocket, TDes8 &aConnectData);

Description

Reserved for future.

Parameters

CBluetoothSocket &aBlankSocket

a socket opened as a blank socket.

TDes8 &aConnectData

Data that may be received in connection.

Return value

TInt

KErrNone if the connection is established. KErrInUse if a connection already exists.


CancelAccept()

IMPORT_C void CancelAccept();

Description

Cancels the Accept() operation.

See also:


Listen()

IMPORT_C TInt Listen(TUint qSize);

Description

Sets up a socket to listen for incoming connections.

Before calling this procedure a socket should be opened using Open() and be bound to a local address using Bind().

Listen() creates a queue to hold incoming connections which can be married with blank sockets using Accept().

Once a listen queue has been created it will continue to allow peers to connect until it is full, at which point it will reject any incoming connections as specified by protocol behaviour. When a socket is accepted by the client a space is made available in the queue.

Parameters

TUint qSize

The number of connections allowed in the queue.

Return value

TInt

The 'listen' queue.


Listen()

IMPORT_C TInt Listen(TUint qSize, const TDesC8 &aConnectData);

Description

Reserved for future.

Parameters

TUint qSize

The size of the 'listen' queue.

const TDesC8 &aConnectData

The descriptor for data sent in connection respoonses.

Return value

TInt

The 'listen' queue.


Listen()

IMPORT_C TInt Listen(TUint qSize, TUint16 aServiceBits);

Description

Sets the Service bits in the Class Of Device. If this is successful, the socket will then be set to Listen for incoming connections.

Before calling this procedure a socket should be opened using Open() and be bound to a local address using Bind().

Listen() creates a queue to hold incoming connections which can be married with blank sockets using Accept().

Once a listen queue has been created it will continue to allow peers to connect until it is full, at which point it will reject any incoming connections as specified by protocol behaviour. When a socket is accepted by the client a space is made available in the queue.

Parameters

TUint qSize

The number of connections allowed in the queue.

TUint16 aServiceBits

Return value

TInt

The 'listen' queue.


SetOpt()

IMPORT_C TInt SetOpt(TUint aOptionName, TUint aOptionLevel, TInt aOption);

Description

Sets a socket option.

The socket server has options which are generic to all sockets and protocols may add specific options.

Options available for all protocols can be set with anOptionLevel set to KSOLSocket. See individual protocol notes for other socket options.

Parameters

TUint aOptionName

An option identifier.

TUint aOptionLevel

An option level. Option levels 'group' related options.

TInt aOption

The option value as an integer.

Return value

TInt

The socket options set.


SetOption()

IMPORT_C TInt SetOption(TUint aOptionName, TUint aOptionLevel, const TDesC8 &aOption);

Description

Sets a socket option.

The socket server has options which are generic to all sockets and protocols may add specific options.

Options available for all protocols can be set with anOptionLevel set to KSOLSocket. See individual protocol notes for other socket options.

Parameters

TUint aOptionName

An option identifier.

TUint aOptionLevel

An option level. Option levels 'group' related options.

const TDesC8 &aOption

The option value as a descriptor.

Return value

TInt

The socket options set.


GetOpt()

IMPORT_C TInt GetOpt(TUint aOptionName, TUint aOptionLevel, TDes8 &aOption);

Description

Gets a socket option.

The socket server has options which are generic to all sockets and protocols may add specific options.

Options available for all protocols can be got with anOptionLevel set to KSOLSocket. See individual protocol notes for other socket options.

Parameters

TUint aOptionName

An option identifier.

TUint aOptionLevel

An option level. Option levels 'group' related options.

TDes8 &aOption

The option value as a descriptor.

Return value

TInt

The socket options set.


GetOpt()

IMPORT_C TInt GetOpt(TUint aOptionName, TUint aOptionLevel, TInt &aOption);

Description

Gets a socket option.

The socket server has options which are generic to all sockets and protocols may add specific options.

Options available for all protocols can be got with anOptionLevel set to KSOLSocket. See individual protocol notes for other socket options.

Parameters

TUint aOptionName

An option identifier.

TUint aOptionLevel

An option level. Option levels 'group' related options.

TInt &aOption

The option value as an integer.

Return value

TInt

The socket options set.


Ioctl()

IMPORT_C TInt Ioctl(TUint aLevel, TUint aCommand, TDes8 *aDesc);

Description

Applies an asynchronous control operation on a socket.

Data may be passed and received if a descriptor address is provided as an argument. Only one Ioctl() operation may be outstanding for each socket.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleIoctlCompleteL(TInt aErr)

Parameters

TUint aLevel

Control operation level.

TUint aCommand

ioctl command.

TDes8 *aDesc

Pointer to a descriptor in which data may be sent and received on completion.

Return value

TInt

KErrNone if the ioctl command is applied or KErrInUse if another ioctl command is still being used.


CancelIoctl()

IMPORT_C void CancelIoctl();

Description

Cancels the Ioctl() asynchronous control operation.

See also:


GetDisconnectData()

IMPORT_C TInt GetDisconnectData(TDes8 &aDesc);

Description

Parameters

TDes8 &aDesc

A descriptor for the disconnect data.

Return value

TInt

KErrNone if successful.


LocalName()

IMPORT_C void LocalName(TSockAddr &aSockAddr);

Description

Gets the local address of a socket.

The local address is set either by calling Bind() or it is automatically set when Connect() is called. If a socket is created through Accept() then a socket will inherit the port of its parent unless otherwise specified by a protocol's behaviour.

Parameters

TSockAddr &aSockAddr

The socket address.


LocalPort()

IMPORT_C TUint LocalPort();

Description

Gets the local port of a socket.

Similar to LocalName().

Return value

TUint

The local port of the socket.

See also:


RemoteName()

IMPORT_C void RemoteName(TSockAddr &aSockAddr);

Description

Gets the remote address of a socket.

The remote name (address) of a socket is associated with the remote host the socket is connected to. The remote name is only valid for a connected socket. A socket is either connected through calling Connect() or Accept().

Parameters

TSockAddr &aSockAddr

The remote socket address.


Shutdown()

IMPORT_C TInt Shutdown(RSocket::TShutdown aHow);

Description

Shuts down a connected socket. (The socket cannot be null. The shutdown method allows input and output to be individually stopped for a protocol endpoint.

When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleShutdownCompleteL(TInt aErr)

Parameters

RSocket::TShutdown aHow

Shutdown option. All variants complete when a socket is disconnected.

Return value

TInt

KErrNone if successful or KErrInUse if the system is already trying to shutdown a connected socket.


Shutdown()

IMPORT_C TInt Shutdown(RSocket::TShutdown aHow, const TDesC8 &aDisconnectDataOut, TDes8 &aDisconnectDataIn);

Description

Reserved for future. The socket must not be null. ( When this request completes, notification is sent to the MBluetoothSocketNotifier object supplied when this CBluetoothSocket was constructed. This is done in the function MBluetoothSocketNotifier::HandleShutdownCompleteL(TInt aErr)

Parameters

RSocket::TShutdown aHow

Shutdown option. All variants complete when a socket is disconnected.

const TDesC8 &aDisconnectDataOut

A descriptor to send data.

TDes8 &aDisconnectDataIn

A descriptor to recive data.

Return value

TInt

KErrNone if successful or KErrInUse if the system is already trying to shutdown a connected socket.


CancelAll()

IMPORT_C void CancelAll();

Description

Cancels all outstanding operations.

Calling it will cause all outstanding operations to cancel. Outstanding operations for a socket include: read, write, Ioctl, connect, accept, shutdown and the Baseband event notifier. All of these operations will be completed by this call.


Info()

IMPORT_C TInt Info(TProtocolDesc &aProtocol);

Description

Gets information about the protocol the socket is opened on.

Parameters

TProtocolDesc &aProtocol

The protocol on which the socket is opened. Note that if the socket is a null socket, and aProtocol is a null TProtocolDesc when it is passed in, if will be null on return as well.

Return value

TInt

KErrNone if successful.


Name()

IMPORT_C TInt Name(TName &aName);

Description

Used to get a unique name of a socket.

The name is needed when Transfer() is called.

Parameters

TName &aName

The system name of a socket.

Return value

TInt

KErrNone if successful.


Transfer()

IMPORT_C TInt Transfer(RSocketServ &aServer, const TDesC &aName);

Description

Transfers a socket from one socket server session to another.

It creates the socket in the target session, and removes the socket from the source session. The call is made on an uninitialised RSocket object. The socket system name 'Name()' is used to identify the socket to transfer.

If the call fails, the socket that is being transferred remains with the original session. Success or failure can be checked on the originating socket by calling Info(), which returns KErrNone if the transfer failed, and KErrBadHandle if it succeeded.

Parameters

RSocketServ &aServer

The session to which the socket is being transfered

const TDesC &aName

The system name of the socket being transfered.

Return value

TInt

KErrNone if successful.


PhysicalLinkState()

IMPORT_C TInt PhysicalLinkState(TUint32 &aState);

Description

Get the state of the physical link.

Parameters

TUint32 &aState

The state of the physical link.

Return value

TInt

The state of the physical link.


PreventRoleSwitch()

IMPORT_C TInt PreventRoleSwitch();

Description

Role switching is not allowed.

Return value

TInt

KErrNone if successful.

See also:


AllowRoleSwitch()

IMPORT_C TInt AllowRoleSwitch();

Description

Allow the socket to switch roles.

Return value

TInt

KErrNone if successful.

See also:


RequestMasterRole()

IMPORT_C TInt RequestMasterRole();

Description

Request the socket take on the master role.

Return value

TInt

KErrNone if successful.

See also:


RequestSlaveRole()

IMPORT_C TInt RequestSlaveRole();

Description

Request the socket take on a slave role.

Return value

TInt

KErrNone if successful.

See also:


PreventLowPowerModes()

IMPORT_C TInt PreventLowPowerModes(TUint32 aLowPowerModes);

Description

Prevents low power modes from being activated.

Parameters

TUint32 aLowPowerModes

The low power mode being prevented.

Return value

TInt

KErrNone if successful. KErrInUse if the socket is using automatic sniff mode.

Panic codes

EInvalidOpWhenAutoSniffOn

(10) This API is not allowed when AutoSniff is On


AllowLowPowerModes()

IMPORT_C TInt AllowLowPowerModes(TUint32 aLowPowerModes);

Description

Allow low power modes.

The power modes are indicated by aLowPowerModes.

Parameters

TUint32 aLowPowerModes

The low power mode.

Return value

TInt

KErrNone if successful. KErrInUse if the socket is using automatic sniff mode.

Panic codes

EInvalidOpWhenAutoSniffOn

(10) This API is not allowed when AutoSniff is On


ActivateSniffRequester()

IMPORT_C TInt ActivateSniffRequester();

Description

Return value

TInt

KErrNone if successful. KErrInUse if the socket is using automatic sniff mode.

Panic codes

EInvalidOpWhenAutoSniffOn

(10) This API is not allowed when AutoSniff is On

See also:


ActivateParkRequester()

IMPORT_C TInt ActivateParkRequester();

Description

Activate park requestor.

Return value

TInt

KErrNone if successful. KErrInUse if the socket is using automatic sniff mode.

Panic codes

EInvalidOpWhenAutoSniffOn

(10) This API is not allowed when AutoSniff is On

See also:


CancelLowPowerModeRequester()

IMPORT_C TInt CancelLowPowerModeRequester();

Description

Cancels the low power mode request.

Return value

TInt

KErrNone if successful. KErrInUse if the socket is using automatic sniff mode.

Panic codes

EInvalidOpWhenAutoSniffOn

(10) This API is not allowed when AutoSniff is On

See also:


RequestChangeSupportedPacketTypes()

IMPORT_C TInt RequestChangeSupportedPacketTypes(TUint16 aPacketTypes);

Description

Request to change the supported packet types.

Parameters

TUint16 aPacketTypes

Return value

TInt

KErrNone if successful.


ActivateBasebandEventNotifier()

IMPORT_C TInt ActivateBasebandEventNotifier(TUint32 aEventTypes);

Description

Set up notification of baseband events

Elect to be notified whenever one of a user specified selection of baseband events occurs.

The notification takes place in the pure virtual function MBluetoothSocketNotifier::HandleActivateBasebandEventNotifierCompleteL(TInt aErr, TBTBasebandEventNotification& aEventNotification)

The FIRST notification will take place ALMOST INSTANTANEOUSLY and will be A FULL DESCRIPTION (OR SNAPSHOT) OF THE CURRENT STATE OF THE PHYSICAL LINK irrespective of the specified selection of events wanted. This first notification or snapshot has NOTHING to do with a baseband event occurring. Once this snapshot has taken place, all occurrences of the specified events from the instant of the snapshot onwards will be notified until CBluetoothSocket::CancelBasebandEventNotifier() is called.

Parameters

TUint32 aEventTypes

bitmask for those events for which notification is being requested (Combine elements of TBTPhysicalLinkStateNotifier and TBTPhysicalLinkStateNotifierCombinations)

Return value

TInt

KErrNone if activated or KErrInUse if the baseband event notifier is already being used.

See also:


CancelBasebandEventNotifier()

IMPORT_C void CancelBasebandEventNotifier();

Description

Cancels an active baseband notifier.

No further baseband events will be notified.

If this function is called when there is no active baseband notifier, it will do nothing.


SetNotifier()

IMPORT_C void SetNotifier(MBluetoothSocketNotifier &aNewNotifier);

Description

Changes the owner (receiver of notifications) of the socket.

The previous notifier will not be deleted after the change has been made.

Parameters

MBluetoothSocketNotifier &aNewNotifier

The object which will receive asynchronous events.


SetAutomaticSniffMode()

IMPORT_C TInt SetAutomaticSniffMode(TBool aAutoSniffMode);

Description

Sets up automatic sniff/unsniff requesting for the socket.

If Automatic Sniff requesting is being selected, a timer with default delay in seconds before the idle socket will request the link to go into sniff mode. The CBluetoothSocket::Write() method will clear an outstanding sniff requester and start the CAutoSniffDelayTimer active object which will issue another request for sniff mode once it times out.

If Automatic Sniff requesting is being deselected, a previous sniff requester will be cancelled.

If Automatic Sniff requesting is selected when it is already active, no change will be performed and KErrInUse will be returned

Parameters

TBool aAutoSniffMode

ETrue if Automatic Sniff/Unsniff requests are required.

Return value

TInt

KErrNone if the automatic sniff mode has been successfully changed. KErrInUse if automatic sniff mode is requested, when it is already active. KErrArgument if an invalid idle timer value for the sniff request is provided. A Symbian wide error code for another other error that might have occurred.


SetAutomaticSniffMode()

IMPORT_C TInt SetAutomaticSniffMode(TBool aAutoSniffMode, TInt aIdleSecondsBeforeSniffRequest);

Description

Sets up automatic sniff/unsniff requesting for the socket.

If Automatic Sniff requesting is being selected, supply the delay in seconds required before the idle socket will request the link to go into sniff mode. The CBluetoothSocket::Write() method will clear an outstanding sniff requester and start the CAutoSniffDelayTimer active object which will issue another request for sniff mode once it times out.

If Automatic Sniff requesting is being deselected, a previous sniff requester will be cancelled.

If Automatic Sniff requesting is selected when it is already active, no change will be performed and KErrInUse will be returned

Parameters

TBool aAutoSniffMode

ETrue if Automatic Sniff/Unsniff requests are required.

TInt aIdleSecondsBeforeSniffRequest

A delay after the socket becomes idle before it will request sniff mode.

Return value

TInt

KErrNone if the automatic sniff mode has been successfully changed. KErrInUse if automatic sniff mode is requested, when it is already active. KErrArgument if an invalid idle timer value for the sniff request is provided. A Symbian wide error code for another other error that might have occurred.


AutomaticSniffMode()

IMPORT_C TBool AutomaticSniffMode() const;

Description

Reports the automatic sniff/unsniff requesting status of the socket.

Return value

TBool

ETrue if automatic sniff/unsniff has been selected for this socket.


AsyncDelete()

IMPORT_C void AsyncDelete();

Description

Asynchronous deletion of the CBluetoothSocket object.

Function will cause asynchronous deletion of CBluetoothSocket object. It should be called if associated MBluetoothSocketNotifier needs to delete CBluetoothSocket from any of its callback functions.


Ioctl()

IMPORT_C TInt Ioctl(TUint aCommand, TDes8 *aDesc=0,TUint aLevel=KLevelUnspecified);

Description

Parameters

TUint aCommand

TDes8 *aDesc

TUint aLevel

Return value

TInt


SetOpt()

IMPORT_C TInt SetOpt(TUint aOptionName, TUint aOptionLevel, const TDesC8 &aOption=TPtrC8(0,0));

Description

Parameters

TUint aOptionName

TUint aOptionLevel

const TDesC8 &aOption

Return value

TInt