# class KToolInvocation

###

Module | kdecore
Namespace |
Class | KToolInvocation
Inherits | QObject

KToolInvocation: for starting other programs

Desktop files for startServiceBy

The way a service gets started depends on the 'X-DBUS-StartupType' entry in the desktop file of the service:

There are three possibilities:

- X-DBUS-StartupType=None (default)
Always start a new service, don't wait till the service registers with dbus.
- X-DBUS-StartupType=Multi
Always start a new service, wait until the service has registered with dbus.
- X-DBUS-StartupType=Unique
Only start the service if it isn't already running, wait until the service has registered with dbus. The .desktop file can specify the name that the application will use when registering using X-DBUS-ServiceName=org.domain.mykapp. Otherwise org.kde.binaryname is assumed.

Multi-threading

The static members (apart from self()), have to be called from the QApplication main thread. Calls to members are only allowed if there is a Q(Core)Application object created If you call the members with signal/slot connections across threads, you can't use the return values If a function is called from the wrong thread and it has a return value -1 is returned Investigate if this is really needed or if DCOP/DBUS is threadsafe anyway

### methods

- KToolInvocation ( )

  returns ctor
  Not implemented

- invokeBrowser (url, startup_id)

  returns Nothing
  static

  Argument | Type | Default
  --- | --- | ---
  url | QString |
  startup_id | QByteArray | QByteArray()

  Invokes the standard browser. Note that you should only do this when you know for sure that the browser can handle the URL (i.e. its mimetype). In doubt, if the URL can point to an image or anything else than directory or HTML, prefer to use new KRun( url ).

  url - The destination address

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

- invokeHelp (anchor, appname, startup_id)

  returns Nothing
  static

  Argument | Type | Default
  --- | --- | ---
  anchor | QString | QString()
  appname | QString | QString()
  startup_id | QByteArray | QByteArray()

  Invokes the KHelpCenter HTML help viewer from docbook sources.

  anchor - This has to be a defined anchor in your docbook sources. If empty the main index is loaded

  appname - This allows you to show the help of another application. If empty the current name() is used

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

- invokeMailer (address, subject, startup_id)

  returns Nothing
  static

  Argument | Type | Default
  --- | --- | ---
  address | QString |
  subject | QString |
  startup_id | QByteArray | QByteArray()

  Convenience method; invokes the standard email application.

  address - The destination address

  subject - Subject string. Can be QString().

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

- invokeMailer (mailtoURL, startup_id, allowAttachments)

  returns Nothing
  static

  Argument | Type | Default
  --- | --- | ---
  mailtoURL | KUrl |
  startup_id | QByteArray | QByteArray()
  allowAttachments | bool | 0

  Invokes the standard email application.

  mailtoURL - A mailto URL.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

  allowAttachments - whether attachments specified in mailtoURL should be honoured. The default is false; do not honor requests for attachments.

- invokeMailer (to, cc, bcc, subject, body, messageFile, attachURLs, startup_id)

  returns Nothing
  static

  Argument | Type | Default
  --- | --- | ---
  to | QString |
  cc | QString |
  bcc | QString |
  subject | QString |
  body | QString |
  messageFile | QString | QString()
  attachURLs | QStringList | QStringList()
  startup_id | QByteArray | QByteArray()

  Convenience method; invokes the standard email application.

  All parameters are optional.

  to - The destination address.

  cc - The Cc field

  bcc - The Bcc field

  subject - Subject string

  body - A string containing the body of the mail (exclusive with messageFile)

  messageFile - A file (URL) containing the body of the mail (exclusive with body) - currently unsupported

  attachURLs - List of URLs to be attached to the mail.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

- invokeTerminal (command, startup_id)

  returns Nothing
  static
  KDE 4.1.0 and later only

  Argument | Type | Default
  --- | --- | ---
  command | QString |
  startup_id | QByteArray | ""

  Invokes the standard terminal application.

  command - the command to execute

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

  @since 4.1

- kapplication_hook (env, startup_id)

  returns Nothing
  SIGNAL ("kapplication_hook (QStringList&, QByteArray&)")

  Argument | Type | Default
  --- | --- | ---
  env | QStringList |
  startup_id | QByteArray |

  Hook for KApplication in kdeui Internal

- kdeinitExec (name, args, error, startup_id)

  returns int, int (pid)
  static

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  args | QStringList | QStringList()
  error | QString | 0
  startup_id | QByteArray | QByteArray()

  Starts a program via kdeinit.

  program name and arguments are converted to according to the local encoding and passed as is to kdeinit.

  name - Name of the program to start

  args - Arguments to pass to the program

  error - On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored

  pid - On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default Returns an error code indicating success (== 0) or failure (> 0).

- kdeinitExecWait (name, args, error, startup_id)

  returns int, int (pid)
  static

  Argument | Type | Default
  --- | --- | ---
  name | QString |
  args | QStringList | QStringList()
  error | QString | 0
  startup_id | QByteArray | QByteArray()

  Starts a program via kdeinit and wait for it to finish.

  Like kdeinitExec(), but it waits till the program is finished. As such it behaves similar to the system(...) function.

  name - Name of the program to start

  args - Arguments to pass to the program

  error - On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored

  pid - On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default Returns an error code indicating success (== 0) or failure (> 0).

- klauncher ( )

  returns OrgKdeKLauncherInterface
  Not implemented

  Returns the DBus interface of the service launcher. The returned object is owned by KApplication, do not delete it!

- self ( )

  returns KToolInvocation
  static

- startServiceByDesktopName (_name, URL, error, serviceName, startup_id, noWait)

  returns int, int (pid)
  static

  Argument | Type | Default
  --- | --- | ---
  _name | QString |
  URL | QString |
  error | QString | 0
  serviceName | QString | 0
  startup_id | QByteArray | QByteArray()
  noWait | bool | 0

  Starts a service based on the desktop name of the service. E.g. "konqueror"

  _name - the desktop name of the service

  URL - if not empty this URL is passed to the service

  error - On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored

  serviceName - On success, serviceName contains the D-Bus service name under which this service is available. If empty, the service does not provide D-Bus services. If the pointer is 0 the argument will be ignored

  pid - On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

  noWait - if set, the function does not wait till the service is running. Returns an error code indicating success (== 0) or failure (> 0).

- startServiceByDesktopName (_name, URLs, error, serviceName, startup_id, noWait)

  returns int, int (pid)
  static

  Argument | Type | Default
  --- | --- | ---
  _name | QString |
  URLs | QStringList | QStringList()
  error | QString | 0
  serviceName | QString | 0
  startup_id | QByteArray | QByteArray()
  noWait | bool | 0

  Starts a service based on the desktop name of the service. E.g. "konqueror"

  _name - the desktop name of the service

  URLs - if not empty these URLs will be passed to the service

  error - On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored

  serviceName - On success, serviceName contains the D-Bus service name under which this service is available. If empty, the service does not provide D-Bus services. If the pointer is 0 the argument will be ignored

  pid - On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

  noWait - if set, the function does not wait till the service is running. Returns an error code indicating success (== 0) or failure (> 0).

- startServiceByDesktopPath (_name, URL, error, serviceName, startup_id, noWait)

  returns int, int (pid)
  static

  Argument | Type | Default
  --- | --- | ---
  _name | QString |
  URL | QString |
  error | QString | 0
  serviceName | QString | 0
  startup_id | QByteArray | QByteArray()
  noWait | bool | 0

  Starts a service based on the desktop path of the service. E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"

  _name - the path of the desktop file

  URL - if not empty this URL is passed to the service

  error - On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored

  serviceName - On success, serviceName contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored

  pid - On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

  noWait - if set, the function does not wait till the service is running. Returns an error code indicating success (== 0) or failure (> 0).

- startServiceByDesktopPath (_name, URLs, error, serviceName, startup_id, noWait)

  returns int, int (pid)
  static

  Argument | Type | Default
  --- | --- | ---
  _name | QString |
  URLs | QStringList | QStringList()
  error | QString | 0
  serviceName | QString | 0
  startup_id | QByteArray | QByteArray()
  noWait | bool | 0

  Starts a service based on the desktop path of the service. E.g. "Applications/konqueror.desktop" or "/home/user/bla/myfile.desktop"

  _name - the path of the desktop file

  URLs - if not empty these URLs will be passed to the service

  error - On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored * serviceName - On success, serviceName contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored

  pid - On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

  noWait - if set, the function does not wait till the service is running. Returns an error code indicating success (== 0) or failure (> 0).

- startServiceByName (_name, URL, error, serviceName, startup_id, noWait)

  returns int, int (pid)
  static

  Argument | Type | Default
  --- | --- | ---
  _name | QString |
  URL | QString |
  error | QString | 0
  serviceName | QString | 0
  startup_id | QByteArray | QByteArray()
  noWait | bool | 0

  Starts a service based on the (translated) name of the service. E.g. "Web Browser"

  _name - the name of the service

  URL - if not empty this URL is passed to the service

  error - On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored

  serviceName - On success, serviceName contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored

  pid - On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

  noWait - if set, the function does not wait till the service is running. Returns an error code indicating success (== 0) or failure (> 0).

- startServiceByName (_name, URLs, error, serviceName, startup_id, noWait)

  returns int, int (pid)
  static

  Argument | Type | Default
  --- | --- | ---
  _name | QString |
  URLs | QStringList | QStringList()
  error | QString | 0
  serviceName | QString | 0
  startup_id | QByteArray | QByteArray()
  noWait | bool | 0

  Starts a service based on the (translated) name of the service. E.g. "Web Browser"

  _name - the name of the service

  URLs - if not empty these URLs will be passed to the service

  error - On failure, error contains a description of the error that occurred. If the pointer is 0, the argument will be ignored

  serviceName - On success, serviceName contains the DCOP name under which this service is available. If empty, the service does not provide DCOP services. If the pointer is 0 the argument will be ignored

  pid - On success, the process id of the new service will be written here. If the pointer is 0, the argument will be ignored.

  startup_id - for app startup notification, "0" for none, "" ( empty string ) is the default

  noWait - if set, the function does not wait till the service is running. Returns an error code indicating success (== 0) or failure (> 0).