class QNativeIpcKey

The QNativeIpcKey class holds a native key used by QSystemSemaphore and QSharedMemory . More…

Added in version 6.6.

Synopsis

Methods

Static functions

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description

The QSharedMemory and QSystemSemaphore classes identify their resource using a system-wide identifier known as a “key”. The low-level key value as well as the key type are encapsulated in Qt using the QNativeIpcKey class.

Those two classes also provide the means to create native keys from a cross-platform identifier, using QSharedMemory::platformSafeKey() and QSystemSemaphore::platformSafeKey(). Applications should never share the input to those functions, as different versions of Qt may perform different transformations, resulting in different native keys. Instead, the application that created the IPC object should communicate the resulting native key using the methods described below.

For details on the key types, platform-specific limitations, and interoperability with older or non-Qt applications, see the Native IPC Keys documentation. That includes important information for sandboxed applications on Apple platforms, including all apps obtained via the Apple App Store.

Communicating keys to other processes

Communicating keys to other Qt processes

If the other process supports QNativeIpcKey , the best way of communicating is via the string representation obtained from toString() and parsing it using fromString() . This representation can be stored on a file whose name is well-known or passed on the command-line to a child process using setArguments() .

If the other process does not support QNativeIpcKey , then the two processes can exchange the nativeKey() but the older code is likely unable to adjust its key type. The legacyDefaultTypeForOs() function returns the type that legacy code used, which may not match the DefaultTypeForOs constant. This is still true even if the old application is not using the same build as the new one (for example, it is a Qt 5 application), provided the options passed to the Qt configure script are the same.

Communicating keys to non-Qt processes

When communicating with non-Qt processes, the application must arrange to obtain the key type the other process is using. This is important particularly on Unix systems, where both PosixRealtime and SystemV are common.

String representation of native keys

The format of the string representation of a QNativeIpcKey is meant to be stable and therefore backwards and forwards compatible, provided the key type is supported by the Qt version in question. That is to say, an older Qt will fail to parse the string representation of a key type introduced after it was released. However, successfully parsing a string representation does not imply the Qt classes can successfully create an object of that type; applications should verify support using QSharedMemory::isKeyTypeSupported() and QSystemSemaphore::isKeyTypeSupported().

The format of the string representation is formed by two components, separated by a colon (‘:’). The first component is the key type, described in the table below. The second component is a type-specific payload, using percent-encoding . For all currently supported key types, the decoded form is identical to the contents of the nativeKey() field.

Key type

String representation

PosixRealtime

"posix"

SystemV

"systemv"

Windows

"windows"

Non-standard SystemV

"systemv-" followed by a decimal number

This format resembles a URI and allows parsing using URI/URL-parsing functions, such as QUrl . When parsed by such API, the key type will show up as the scheme , and the payload will be the path . Use of query or fragments is reserved.

class Type

This enum describes the backend type for the IPC object. For details on the key types, see the Native IPC Keys documentation.

Constant

Description

QNativeIpcKey.Type.SystemV

X/Open System Initiative (XSI) or System V (SVr4) API

QNativeIpcKey.Type.PosixRealtime

IEEE 1003.1b (POSIX.1b) API

QNativeIpcKey.Type.Windows

Win32 API

See also

setType() type()

PySide6.QtCore.QNativeIpcKey.DefaultTypeForOs
__init__()

Constructs a QNativeIpcKey object of type DefaultTypeForOs with an empty key.

__init__(type)
Parameters:

type – Type

__init__(other)
Parameters:

other – QNativeIpcKey

__init__(k[, type=QNativeIpcKey.DefaultTypeForOs])
Parameters:

  • k – str

  • type – Type

static fromString(string)
Parameters:

string – str

Return type:

QNativeIpcKey

Parses the string form text and returns the corresponding QNativeIpcKey . String representations are useful to inform other processes of the key this process created and they should attach to.

If the string could not be parsed, this function returns an invalid object.

isEmpty()
Return type:

bool

Returns true if the nativeKey() is empty.

See also

nativeKey()

isValid()
Return type:

bool

Returns true if this object contains a valid native IPC key type. Invalid types are usually the result of a failure to parse a string representation using fromString() .

This function performs no check on the whether the key string is actually supported or valid for the current operating system.

See also

type() fromString()

static legacyDefaultTypeForOs()
Return type:

Type

Returns the Type that corresponds to the native IPC key that QSharedMemory and QSystemSemaphore used to use prior to Qt 6.6. Applications and libraries that must retain compatibility with code using either class that was compiled with Qt prior to version 6.6 can use this function to determine what IPC type the other applications may be using.

Note that this function relies on Qt having been built with identical configure-time options.

nativeKey()
Return type:

str

Returns the native key string associated with this object.

__ne__(rhs)
Parameters:

rhs – QNativeIpcKey

Return type:

bool

__eq__(rhs)
Parameters:

rhs – QNativeIpcKey

Return type:

bool

setNativeKey(newKey)
Parameters:

newKey – str

Sets the native key for this object to newKey.

setType(type)
Parameters:

type – Type

Sets the IPC type of this object to type.

swap(other)
Parameters:

other – QNativeIpcKey

Swaps the native IPC key and type other with this object. This operation is very fast and never fails.

toString()
Return type:

str

Returns the string representation of this object. String representations are useful to inform other processes of the key this process created and that they should attach to.

This function returns a null string if the current object is invalid .

See also

fromString()

type()
Return type:

Type

Returns the key type associated with this object.