SxeProgramInfo Class Reference
[QtBaseModule]

Detailed Description

The SxeProgramInfo class is a data transfer object that models a program on disk.

Used for registration of binaries with the SXE system.

Registration can happen at run-time of the qtopia device or at install-time, when building the qtopia ROM image on a development host.

For example, consider the following binaries installed onto a device:

    /opt/Qtopia.rom/bin/calculator
    /opt/Qtopia.user/packages/bin/bomber

These examples are referenced in the documentation of public variables below. The table below summarizes the difference between "qbuild image" time and run time.

The runRoot must be one of the elements which will be returned by the Qtopia::installPaths() method at runtime.

The installRoot is optional and will be empty in the case of a binary installed at run-time by the package manager.

Member Function Documentation

SxeProgramInfo::SxeProgramInfo ()

Construct a new SxeProgramInfo

SxeProgramInfo::~SxeProgramInfo ()

Destroy this SxeProgramInfo object

QString SxeProgramInfo::absolutePath () const

Return the QString of the absolute path to the binary for this SxeProgramInfo object.

This is simply the concatenation of installRoot, relPath and fileName. If the installRoot is null, the runRoot is used instead.

isValid() can be called to check that the returned path will point to a valid binary.

bool SxeProgramInfo::isValid () const

Return true if the SxeProgramInfo object represents a valid binary for SXE registration, and otherwise return false.

The binary is valid if all of the components of absolutePath() above are non-empty, and the resulting path is to a file which exists

bool SxeProgramInfo::locateBinary ()

Try to find this binary in the current file-system. First a check is made to see if isValid() returns true: if so this method simply returns true.

Otherwise an attempt to find the binary is made by traversing the entries in Qtopia::installPaths().

The fileName member should be set to non-empty before calling this method otherwise it simply returns false.

If the relPath member is set, then only that path is checked under each of the installPaths().

If the relPath member is empty, then the path searched is decided by checking if the filename refers to a shared library or not: if the fileName starts with "lib" and ends with ".so" then "application/plugins" are checked, otherwise only "bin" is checked.

If the binary is found, the relPath and runRoot entries are set to the the location, and the method returns true.

If the binary is not found, no entries are altered and the method returns false.

For example:

    SxeProgramInfo calcBin;
    calcBin.fileName = "calculator";
    if ( calcBin.locateBinary() )
        qDebug() << "Calculator is a standalone app at" << calcBin.absolutePath();
    else
    {
        calcBin.fileName = "libcalculator.so";
        if ( calcBin.locateBinary() )
            qDebug() << "Calculator is a quicklaunched app at" << calcBin.absolutePath();
        else
            qDebug() << "Calculator is not available";
    }

void SxeProgramInfo::suid ()

Make the current process assume the SXE identity of the executable represented by this SxeProgramInfo.

Internally this is done by writing to the /proc/lids/suid pseudo file.

This method only succeeds on a suitably patched SXE linux kernel.

Member Variable Documentation

QString SxeProgramInfo::domain

security domains, a list of comma seperated values

QString SxeProgramInfo::fileName

the binaries file name, eg calculator, bomber

unsigned char SxeProgramInfo::id

SXE program identity

QString SxeProgramInfo::installRoot

for example $HOME/build/qtopia/42-phone/image this should only ever be set when running under sxe_installer

char SxeProgramInfo::key[QSXE_KEY_LEN]

SXE shared secret key

QString SxeProgramInfo::relPath

for example bin, packages/bin, plugings/application

QString SxeProgramInfo::runRoot

for example /opt/Qtopia.rom, /opt/Qtopia.user

Related Non-Members

void checkAndSetProcessKey ( const char * key, const char * app )

Ensure the SXE key for this executable is valid, and then call the transport authorizer method to set it.

After this call all QWS calls by app will be authorized with this key.

A check is made that the binary has been keyed, and if not then the method will qFatal, with the message "SXE key has not been set".

(This function is stubbed out with an empty implementation if Qt Extended is configured without SXE.)

QDebug operator<< ( QDebug debug, const SxeProgramInfo & progInfo )

This is an overloaded member function, provided for convenience.

Sends the SxeProgramInfo progInfo to the debug stream.

Macro Documentation

QSXE_APP_KEY

This macro causes the key storage to be allocated and initialized. An application without this macro cannot be used on a SXE-enabled system. It is needed if you are not using the QTOPIA_MAIN macro.

    QSXE_APP_KEY
    int main( int argc, char **argv )
    {
        QSXE_SET_APP_KEY(argv[0]);
        ...

See also Applications and QTOPIA_APP_KEY.

QSXE_QL_APP_KEY

This macro causes the key storage to be allocated and initialized. An application without this macro cannot be used on a SXE-enabled system. It is needed if you are not using the QTOPIA_MAIN macro.

Note that this macro only applies to quicklaunch plugins.

See also Applications and QTOPIA_APP_KEY.

QSXE_SET_APP_KEY ( name )

This macro causes the SXE key to be copied into memory. It is needed if you are not using the QTOPIA_MAIN macro. It must be the first line of your main() function. The name value should be set to the binary's name.

    QSXE_APP_KEY
    int main( int argc, char **argv )
    {
        QSXE_SET_APP_KEY(argv[0]);
        ...

See also Applications and QTOPIA_SET_KEY().

QSXE_SET_QL_KEY ( name )

This macro causes the SXE key to be copied into memory. It is needed if you are not using the QTOPIA_MAIN macro. It must be called before constructing QtopiaApplication. The name value should be set to the binary's name.

Note that this macro only applies to quicklaunch plugins.

See also Applications and QTOPIA_SET_KEY().