»
Developer Library »
API Reference »
C++ API reference »
Secure Sockets »
CSecureSocket
Location:
SecureSocket.h
Link against: securesocket.lib
class CSecureSocket : public CBase, public MSecureSocket;
Support
Supported from 7.0
Description
Secure sockets class.
Derivation
CBase | Base class for all classes to be instantiated on the heap |
CSecureSocket | Secure sockets class |
MSecureSocket | Abstract interface API for secure socket implementations |
|
Defined in CSecureSocket:
AvailableCipherSuites(), CancelAll(), CancelHandshake(), CancelRecv(), CancelSend(), ClientCert(), ClientCertMode(), Close(), ConstructL(), CurrentCipherSuite(), DialogMode(), FlushSessionCache(), GetOpt(), GetOpt(), NewL(), Protocol(), Recv(), RecvOneOrMore(), RenegotiateHandshake(), Send(), Send(), ServerCert(), SetAvailableCipherSuites(), SetClientCert(), SetClientCertMode(), SetDialogMode(), SetOpt(), SetOpt(), SetProtocol(), SetServerCert(), StartClientHandshake(), StartServerHandshake(), iLibEntryPoint, iSecureImplementation, ~CSecureSocket()
Inherited from CBase:
operator new()
Construction and destruction
static CSecureSocket* NewL(RSocket& aSocket, const TDesC& aProtocol);
Description
Creates and returns a pointer to a new secure socket. A reference to an already open and connected socket should be passed in, along with a descriptor that contains the protocol name.
Parameters
RSocket& aSocket |
A reference to an open and connected RSocket class. |
const TDesC& aProtocol |
A constant descriptor containing the protocol name. |
|
Return value
CSecureSocket
*
|
A pointer to the newly created secure socket, or NULL if the creation failed. |
|
~CSecureSocket();
Description
Standard destructor.
TInt AvailableCipherSuites(TDes8& aCiphers);
Description
Returns the available cipher suites.
Parameters
TDes8& aCiphers |
Descriptor holding the ciphers. |
|
Return value
TInt
|
KErrNone if successful, a system-wide error code if not.
|
|
void CancelAll();
Description
Cancels all the send and receive actions in the SSL state machine.
void CancelHandshake();
Description
Cancels the handshake.
void CancelRecv();
Description
Cancels a receive action in the SSL state machine.
void CancelSend();
Description
Cancels a send action in the SSL state machine.
const CX509Certificate* ClientCert();
Description
Gets the current client certificate.
When a secure socket is acting in server mode, the returned certificate will be the certificate that the remote
client provided.
When acting in client mode, the certificate returned will be local certificate.
Return value
TClientCertMode ClientCertMode();
Description
Returns the current client certificate mode.
The client certificate mode is used when the socket is acting as a server, and determines whether a
client certificate is requested.
Return value
TDialogMode DialogMode();
Description
Returns the current dialog mode.
Return value
void Close();
Description
Closes the secure connection and the socket.
Implementations should terminate the secure connection gracefully as appropriate to their protocol. The RSocket object is not destoyed: this is left to the client application.
TInt CurrentCipherSuite(TDes8& aCipherSuite);
Description
Gets the current cipher suite in use.
The current cipher suite is returned in the referenced buffer in two byte format as, i.e. [0x??][0x??].
Parameters
TDes8& aCipherSuite |
A reference to a descriptor at least 2 bytes long. Implementations that differ
from the [0x??][0x??] format may require larger descriptors. See individual implementation notes
for details. |
|
Return value
TInt
|
Any one of the system error codes, or KErrNone on success. |
|
void FlushSessionCache();
Description
Flushes the session cache.
TInt GetOpt(TUint aOptionName, TUint aOptionLevel, TDes8& aOption);
Description
Gets an option.
Secure socket implementations may provide options that can be used with this method.
Parameters
TUint aOptionName |
An integer constant which identifies an option.
|
TUint aOptionLevel |
An integer constant which identifies the level of an option, i.e. an option level group of related options. |
TDes8& aOption |
An option value packaged in a descriptor. |
|
Return value
TInt
|
KErrNone if successful, otherwise another of the system-wide error codes.
|
|
TInt GetOpt(TUint aOptionName, TUint aOptionLevel, TInt& aOption);
Description
Gets an option.
Secure socket implementations may provide options that can be used with this method.
Parameters
TUint aOptionName |
An integer constant which identifies an option. |
TUint aOptionLevel |
An integer constant which identifies the level of an option, i.e. an option level group of related options. |
TInt& aOption |
An option value as an integer. |
|
Return value
TInt
|
KErrNone if successful, otherwise another of the system-wide error codes.
|
|
TInt Protocol(TDes& aProtocol);
Description
Gets the protocol in use.
This method can be used to return the particular protocol/version that is being used by
implementations that support different protocols/versions.
Parameters
TDes& aProtocol |
A descriptor containing the protocol name/version that is being used.
Protocol names can be up to 32 characters long, and so a descriptor of at least that
size is required. |
|
Return value
void Recv(TDes8& aDesc, TRequestStatus& aStatus);
Description
Receive data from the socket.
This is an asynchronous method, and will complete when the descriptor has been filled.
Only one Recv() or RecvOneOrMore() operation can be outstanding at any time.
Parameters
TDes8& aDesc |
A descriptor where data read will be placed. |
TRequestStatus& aStatus |
On completion, KErrNone if successful, KErrEof if a remote connection is closed and there is no more data, KErrNotReady if called when an operation is still outstanding, or a system-wide error code. |
|
void RecvOneOrMore(TDes8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen);
Description
Receives data from the socket.
This is an asynchronous call, and will complete when at least one byte has been read. Only one Recv() or RecvOneOrMore() operation can be outstanding at any time.
Parameters
TDes8& aDesc |
A descriptor where data read will be placed. |
TRequestStatus& aStatus |
On completion, KErrNone if successful, KErrEof if a remote connection is closed and there is no more data, KErrNotReady if called when an operation is still outstanding, or a system-wide error code. |
TSockXfrLength& aLen |
On completion, the length of the descriptor, aDesc. |
|
void RenegotiateHandshake(TRequestStatus& aStatus);
Description
Initiates a renegotiation of the secure connection.
This is an asynchronous method that completes when renegotiation is complete.
It is valid for both client and server operation.
There can only be one outstanding RenegotiateHandshake() operation at a time.
Parameters
void Send(const TDesC8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen);
Description
Sends data over the socket.
This is an asynchronous call. Only one Send() operation can be outstanding at any time.
Parameters
const TDesC8& aDesc |
A constant descriptor with the data to be send. |
TRequestStatus& aStatus |
On completion, KErrNone if successful, KErrNotReady if called when an operation is still outstanding, or a system-wise error code. |
TSockXfrLength& aLen |
On completion, the amount of data sent. |
|
void Send(const TDesC8& aDesc, TRequestStatus& aStatus);
Description
Sends data over the socket.
This is an asynchronous call. Only one Send() operation can be outstanding at any time,
and the function will complete with the error KErrNotReady if called when a send is still outstanding.
Parameters
const TDesC8& aDesc |
A constant descriptor. The application must not modify this descriptor until
the Send() completes. |
TRequestStatus& aStatus |
On completion KErrNone, KErrNotReady if called when a send is still outstanding if successful, or asystem-wide error code. |
|
const CX509Certificate* ServerCert();
Description
Gets the current server certificate.
When a secure socket is acting in client mode, the returned certificate will be the certificate
for the remote server.
When acting in server mode, the certificate returned will be the local certificate.
Note: Operation in server mode is currently reserved for future use, and returns NULL.
Return value
const
CX509Certificate*
|
Pointer to the certificate, or NULL if no certificate is available. |
|
SetAvailableCipherSuites()
TInt SetAvailableCipherSuites(const TDesC8& aCiphers);
Description
Sets the list of cipher suites that are available for use.
The list of cipher suites should be supplied in a descriptor in the format as per the TLS RFC, i.e. [0x??][0x??] for each suite. The order of suites is important, and so they should be listed
with the preferred suites first.
Parameters
const TDesC8& aCiphers |
Descriptor holding the cipher suites list. |
|
Return value
TInt
|
KErrNone if successful, a system-wide error code if not.
|
|
TInt SetClientCert(const CX509Certificate& aCert);
Description
Sets the client certificate to use.
When a secure socket is acting in client mode, this method will set the certificate that will be
used if a server requests one.
When acting in server mode, if called this method will perform no action, but will return KErrNotSupported.
Note: This method is currently reserved for future use, and always returns KErrNotSupported.
Parameters
Return value
TInt
|
KErrNone if successful, a system-wide error code if not.
|
|
TInt SetClientCertMode(const TClientCertMode aClientCertMode);
Description
Sets the client certificate mode.
Parameters
Return value
TInt
|
KErrNone if successful, a system-wide error code if not.
|
|
TInt SetDialogMode(const TDialogMode aDialogMode);
Description
Sets the Dialog mode.
Parameters
Return value
TInt
|
KErrNone if successful, a system-wide error code if not.
|
|
TInt SetProtocol(const TDesC& aProtocol);
Description
Sets the protocol
Parameters
const TDesC& aProtocol |
Descriptor holding the protocol name to be set, e.g. "SSL3.0" or "TLS1.0". |
|
Return value
TInt SetOpt(TUint aOptionName, TUint aOptionLevel, const TDesC8& aOption=TPtrC8(NULL, 0));
Description
Sets a socket option.
Secure socket implementations may provide options that can be used with this method.
See individual implementation notes for details.
Parameters
TUint aOptionName |
An integer constant which identifies an option. |
TUint aOptionLevel |
An integer constant which identifies the level of an option:
i.e. an option level group of related options. |
const TDesC8& aOption=TPtrC8(NULL, 0) |
An option value packaged in a descriptor. |
|
Return value
TInt
|
KErrNone if successful, a system-wide error code if not.
|
|
TInt SetOpt(TUint aOptionName, TUint aOptionLevel, TInt aOption);
Description
Sets an option.
SecureSocket implementations may provide options that can be used with this method.
See individual implementation notes for details.
Parameters
TUint aOptionName |
An integer constant which identifies an option. |
TUint aOptionLevel |
An integer constant which identifies the level of an option:
i.e. an option level group of related options. |
TInt aOption |
An option value as an integer
. |
|
Return value
TInt
|
KErrNone if successful, a system-wide error code if not.
|
|
TInt SetServerCert(const CX509Certificate& aCert);
Description
Sets the server X509 certificate.
Parameters
Return value
TInt
|
KErrNone if successful, a system-wide error code if not.
|
|
void StartClientHandshake(TRequestStatus& aStatus);
Description
Starts the client handshake.
Parameters
void StartServerHandshake(TRequestStatus& aStatus);
Description
Starts the server handshake.
Parameters
private: void ConstructL(RSocket& aSocket, const TDesC& aProtocol);
Description
This member is internal and not intended for use.
private: MSecureSocket* iSecureImplementation;
Description
This member is internal and not intended for use.
private: TSecSockDllLibraryFunction iLibEntryPoint;
Description
This member is internal and not intended for use.
![[Index]](../../../../_stock/btn_index.gif){kind=small}
![[Glossary]](../../../../_stock/btn_glossary.gif){kind=small}
![[Previous]](../../../../_stock/btn_prev.gif){kind=small}
![[Next]](../../../../_stock/btn_next.gif){kind=small}
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../../_stock/arrow_up.gif){kind=icon}