From 0dcfe6f813d75da55c6183acac9a2cdfe2381594 Mon Sep 17 00:00:00 2001 From: Frans Englich Date: Fri, 26 Mar 2010 11:25:32 +0100 Subject: [PATCH] Document Symbian platform security requirements on Qt APIs Work done jointly by Gareth and me. Yields no qdoc errors. Task-number: QTBUG-9342 Task-number: QTBUG-9120 Reviewed-by: Gareth Stockwell Reviewed-by: David Boddie --- doc/src/classes/phonon-api.qdoc | 10 ++++++++++ src/corelib/io/qprocess.cpp | 18 ++++++++++++++++++ src/multimedia/audio/qaudioinput.cpp | 18 ++++++++++++++++++ src/network/access/qnetworkaccessmanager.cpp | 10 ++++++++++ src/network/socket/qtcpserver.cpp | 10 ++++++++++ src/network/socket/qtcpsocket.cpp | 10 ++++++++++ src/network/socket/qudpsocket.cpp | 10 ++++++++++ src/network/ssl/qsslsocket.cpp | 10 ++++++++++ 8 files changed, 96 insertions(+), 0 deletions(-) diff --git a/doc/src/classes/phonon-api.qdoc b/doc/src/classes/phonon-api.qdoc index 98df89d..641b936 100644 --- a/doc/src/classes/phonon-api.qdoc +++ b/doc/src/classes/phonon-api.qdoc @@ -1651,6 +1651,16 @@ playback of the current source, but it is possible to try with a different one. A user readable error message is given by errorString(). + \section1 Symbian Platform Security Requirements + + On Symbian, processes which access media via the network must + have the \c NetworkServices platform security capability. If the client + process lacks this capability, operations will result in errors. + This failure is indicated by a state() of Phonon::ErrorState. + + Platform security capabilities are added via the + \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY} + qmake variable. \sa Phonon::MediaSource, Phonon::AudioOutput, VideoWidget, {Music Player Example}, {Phonon Overview}, Phonon::VideoPlayer, diff --git a/src/corelib/io/qprocess.cpp b/src/corelib/io/qprocess.cpp index 12a992a..af1fc82 100644 --- a/src/corelib/io/qprocess.cpp +++ b/src/corelib/io/qprocess.cpp @@ -551,6 +551,16 @@ void QProcessPrivate::Channel::clear() interpreter itself (\c{cmd.exe} on some Windows systems), and ask the interpreter to execute the desired command. + \section1 Symbian Platform Security Requirements + + On Symbian, processes which use the functions kill() or terminate() + must have the \c PowerMgmt platform security capability. If the client + process lacks this capability, these functions will fail. + + Platform security capabilities are added via the + \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY} + qmake variable. + \sa QBuffer, QFile, QTcpSocket */ @@ -2006,9 +2016,13 @@ void QProcess::start(const QString &program, OpenMode mode) event loop does not handle the WM_CLOSE message, can only be terminated by calling kill(). + On Symbian, this function requires platform security capability + \c PowerMgmt. If absent, the process will panic with KERN-EXEC 46. + \note Terminating running processes from other processes will typically cause a panic in Symbian due to platform security. + \sa \l {Symbian Platform Security Requirements} \sa kill() */ void QProcess::terminate() @@ -2023,6 +2037,10 @@ void QProcess::terminate() On Windows, kill() uses TerminateProcess, and on Unix and Mac OS X, the SIGKILL signal is sent to the process. + On Symbian, this function requires platform security capability + \c PowerMgmt. If absent, the process will panic with KERN-EXEC 46. + + \sa \l {Symbian Platform Security Requirements} \sa terminate() */ void QProcess::kill() diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp index 10bab01..c99e870 100644 --- a/src/multimedia/audio/qaudioinput.cpp +++ b/src/multimedia/audio/qaudioinput.cpp @@ -146,6 +146,20 @@ QT_BEGIN_NAMESPACE \snippet doc/src/snippets/audio/main.cpp 0 \sa QAudioOutput, QAudioDeviceInfo + + \section1 Symbian Platform Security Requirements + + On Symbian, processes which use this class must have the + \c UserEnvironment platform security capability. If the client + process lacks this capability, calls to either overload of start() + will fail. + This failure is indicated by the QAudioInput object setting + its error() value to \l{QAudio::OpenError} and then emitting a + \l{stateChanged()}{stateChanged}(\l{QAudio::StoppedState}) signal. + + Platform security capabilities are added via the + \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY} + qmake variable. */ /*! @@ -197,6 +211,8 @@ QAudioInput::~QAudioInput() If a problem occurs during this process the error() is set to QAudio::OpenError, state() is set to QAudio::StoppedState and stateChanged() signal is emitted. + \sa {Symbian Platform Security Requirements} + \sa QIODevice */ @@ -217,6 +233,8 @@ void QAudioInput::start(QIODevice* device) If a problem occurs during this process the error() is set to QAudio::OpenError, state() is set to QAudio::StoppedState and stateChanged() signal is emitted. + \sa {Symbian Platform Security Requirements} + \sa QIODevice */ diff --git a/src/network/access/qnetworkaccessmanager.cpp b/src/network/access/qnetworkaccessmanager.cpp index 03b7192..acf894c 100644 --- a/src/network/access/qnetworkaccessmanager.cpp +++ b/src/network/access/qnetworkaccessmanager.cpp @@ -138,6 +138,16 @@ static void ensureInitialized() can be: \snippet doc/src/snippets/code/src_network_access_qnetworkaccessmanager.cpp 1 + \section1 Symbian Platform Security Requirements + + On Symbian, processes which use this class must have the + \c NetworkServices platform security capability. If the client + process lacks this capability, operations will result in a panic. + + Platform security capabilities are added via the + \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY} + qmake variable. + \sa QNetworkRequest, QNetworkReply, QNetworkProxy */ diff --git a/src/network/socket/qtcpserver.cpp b/src/network/socket/qtcpserver.cpp index 404eee7..932126d 100644 --- a/src/network/socket/qtcpserver.cpp +++ b/src/network/socket/qtcpserver.cpp @@ -79,6 +79,16 @@ use waitForNewConnection(), which blocks until either a connection is available or a timeout expires. + \section1 Symbian Platform Security Requirements + + On Symbian, processes which use this class must have the + \c NetworkServices platform security capability. If the client + process lacks this capability, it will lead to a panic. + + Platform security capabilities are added via the + \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY} + qmake variable. + \sa QTcpSocket, {Fortune Server Example}, {Threaded Fortune Server Example}, {Loopback Example}, {Torrent Example} */ diff --git a/src/network/socket/qtcpsocket.cpp b/src/network/socket/qtcpsocket.cpp index b1c7c1c..70852a5 100644 --- a/src/network/socket/qtcpsocket.cpp +++ b/src/network/socket/qtcpsocket.cpp @@ -60,6 +60,16 @@ \bold{Note:} TCP sockets cannot be opened in QIODevice::Unbuffered mode. + \section1 Symbian Platform Security Requirements + + On Symbian, processes which use this class must have the + \c NetworkServices platform security capability. If the client + process lacks this capability, it will result in a panic. + + Platform security capabilities are added via the + \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY} + qmake variable. + \sa QTcpServer, QUdpSocket, QFtp, QNetworkAccessManager, {Fortune Server Example}, {Fortune Client Example}, {Threaded Fortune Server Example}, {Blocking Fortune Client Example}, diff --git a/src/network/socket/qudpsocket.cpp b/src/network/socket/qudpsocket.cpp index e208904..d5366d3 100644 --- a/src/network/socket/qudpsocket.cpp +++ b/src/network/socket/qudpsocket.cpp @@ -86,6 +86,16 @@ \l{network/broadcastreceiver}{Broadcast Receiver} examples illustrate how to use QUdpSocket in applications. + \section1 Symbian Platform Security Requirements + + On Symbian, processes which use this class must have the + \c NetworkServices platform security capability. If the client + process lacks this capability, operations will result in a panic. + + Platform security capabilities are added via the + \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY} + qmake variable. + \sa QTcpSocket */ diff --git a/src/network/ssl/qsslsocket.cpp b/src/network/ssl/qsslsocket.cpp index 9623570..7ad471c 100644 --- a/src/network/ssl/qsslsocket.cpp +++ b/src/network/ssl/qsslsocket.cpp @@ -156,6 +156,16 @@ is being encrypted and encryptedBytesWritten() will get emitted as soon as data has been written to the TCP socket. + \section1 Symbian Platform Security Requirements + + On Symbian, processes which use this class must have the + \c NetworkServices platform security capability. If the client + process lacks this capability, operations will fail. + + Platform security capabilities are added via the + \l{qmake-variable-reference.html#target-capability}{TARGET.CAPABILITY} + qmake variable. + \sa QSslCertificate, QSslCipher, QSslError */ -- 1.7.0.2