Development/Tutorials/Services/Traders: Difference between revisions

    From KDE TechBase
    (sketch this one out)
     
    No edit summary
     
    (17 intermediate revisions by 11 users not shown)
    Line 1: Line 1:
    {{TutorialBrowser|
    {{TutorialBrowser|


    series=Services|
    series=Services|


    name=Traders: Querying the System|
    name=Finding Services Using Trader Queries|


    pre=[[../Introduction|Introduction to the Services Framework]]
    pre=[[../Introduction|Introduction to the Services Framework]]|


    next=[[../Plugins|Creating and Loading Plugins Using KService]]|
    next=[[../Plugins|Creating and Loading Plugins Using KService]]|
    Line 13: Line 15:


    == Abstract ==
    == Abstract ==
    It is often desirable to be able to find specific types of services or services with specific features or designations. KDE provides a simple yet powerful query language to accomplish this called the KTrader Query Language.


    == A Tale of Two Traders ==
    == A Tale of Two Traders ==


    == The Syntax ==
    KDE provides two classes that act as "traders". A trader takes a query and returns a set of services that match those constraints. There is one trader for plugins and other add-ons: {{class|KServiceTypeTrader}}, and one for mimetypes: {{class|KMimetypeTrader}}. Characteristics for both are similar: they have same syntax for querying, offer a singleton pattern accessor, return {{class|KService}}::Ptrs, as well as other similarities. So while this tutorial concentrates primarily on the {{class|KServiceTypeTrader}}, much of the content is applicable to the mimetype trader as well.
     
    == Service Types ==
     
    {{class|KServiceTypeTrader}} is used to locate individual components such as application plugins, screensavers, and control panels that are registered with the system. The primary concept used here, is that of the "service type". Each set of services has a unique service type, which makes it very easy to locate the sort of component needed.
     
    This means that, each kind of application plugin is uniquely namespaced within the set of all services. So, it is trivial to locate plugins for a given application, without having to worry about getting another application's plugin in the list.
     
    Examples of service types include:
    *KParts/ReadWritePart
    *KTextEditor/Document
    *ScreenSaver
    *TerminalEmulator
    *UserAgentStrings
    *ThumbCreator
    *KDevelop/Plugin
     
    There is no limit to the number of service types that a given application may use or register. Of course, service types are not limited to plugins and may be used for any sort of data component.
     
    Creating new service types is covered in the next tutorial of this series:
    [[Development/Tutorials/Services/Plugins|Creating and Loading Plugins Using KService]]
     
    == Basic KServiceTypeTrader Usage ==
     
    The service trader is always accessed via the <tt>self()</tt> singleton accessor. With the {{class|KServiceTypeTrader}} in hand, we can then do one of three things:
    *'''query''': query for a list of services ordered according to the user's preferences (if any)
    *'''defaultOffers''': request all services, unsorted
    *'''preferredService''': request the preferred service of a given type
     
    The code to do this is very straight forward:
    <syntaxhighlight lang="cpp-qt">
    KService::List services;
    KServiceTypeTrader* trader = KServiceTypeTrader::self();
     
    services = trader->query("KParts/ReadWritePart");
    foreach (KService::Ptr service, services) {
        kDebug() << "read write part" << service->name();
    }
     
    services = trader->defaultOffers("ThumbCreator");
    if (services.isEmpty()) {
        kDebug() << "no services found for ThumbCreator!";
    }
     
    KService::Ptr service = trader->preferredService("KDevelop/Plugin");
    if (!service) {
        kDebug() << "no preferred service found for KDevelop/Plugin";
    }
    </syntaxhighlight>
     
    In each case zero or more services are returned that are now usable for locating, describing and loading the item it represents.
     
    == The KTrader Query Language ==
     
    The above examples are quite simplistic and are not detailed enough for many application needs. For instance, we may only want to list plugins for a certain category, that are associated with a particular mimetype, or that have a specific plugin name. This is where the query language comes in.
     
    The query language itself is designed to be human readable and flexible. <tt>{{class|KServiceTypeTrader}}::query</tt> optionally takes a query, in addition to the service type, and uses that to provide more fine-grained searches. So, for example, we'll modify the earlier example in the following way:
     
    <syntaxhighlight lang="cpp-qt">
    KService::List services ;
    KServiceTypeTrader* trader = KServiceTypeTrader::self();
     
    QString constraint = "'text/plain' in MimeTypes and "
                        "('KOfficePart' in ServiceTypes or "
                        " 'oasis' ~ [X-KDE-ExtraNativeMimeTypes])";
    services = trader->query("KParts/ReadWritePart", constraint);
     
    foreach (KService::Ptr service, services) {
        kDebug() << "read write part" << service->name();
    }
    </syntaxhighlight>
     
    This code will look for a KPart that is both capable of reading/writing plain text files and is also a KOffice component, or can simply read ODF document formats.
     
    Errors in queries are reported via debug output to console at runtime.
     
    === Order of Operations ===
     
    The query string is evaluated left to right, one section at a time. Sections are divided by boolean operators (see below) or by parentheses ('()'), which serve as grouping characters.


    === Literals ===
    === Literals ===


    === Symbols ===
    Three types of literals are supported by the KTrader Query Language:
    *'''strings''': character strings, which must be enclosed in single quotes (')
    *'''booleans''': TRUE or FALSE
    *'''signed integers'''
    *'''signed floating point numbers'''
     
    === Identifiers ===
    Identifiers in a query string are mapped to entries listed in the service's <tt>.desktop</tt> file. For example, "Name" is the name of the service, "ServiceTypes" is a list of the service types it supports.
     
    Identifiers may only contain alphanumeric characters and the '-' character.
    Identifiers that do not start with an alphabetical character or that contain non-alphanumeric characters must be enclosed in brackets, e.g. [X-KDE-Init].
     
    There are also three special identifiers:
     
    *'''DesktopEntryName''' stands for the filename of the service desktop entry without its extension. This can be useful to exclude some specific services.
    *'''DesktopEntryPath''' stands for the relative or full path to the .desktop file, see {{class|KService}}::desktopEntryPath.
    *'''Library''': a synonym for [X-KDE-Library] in the .desktop file.
     
    An identifier can be checked for existence with the '''exist''' operator, e.g. "exist [X-KDE-Library]". This is especially useful when checking for the value of an identifier with a default value. For example, if MyProp is a property with type boolean, one might write "not exist MyProp or MyProp" to match MyProp with a default of "true".
     
    <syntaxhighlight lang="cpp-qt">
    QString term = "konq";
    QString query = QString("exist Exec and ((exist Keywords and '%1' ~subin Keywords) or (exist GenericName and '%1' ~~ GenericName) or (exist Name and '%1' ~~ Name))").arg(term);
    KService::List services = KServiceTypeTrader::self()->query("Application", query);
    foreach (KService::Ptr service, services) {
        kDebug() << service->name();
    }
    </syntaxhighlight>


    === Comparison Operators ===
    === Comparison Operators ===
    The following comparison operators can be used to compare values of any of the supported data types:
    *'''==''': equality
    *'''!=''': inequality
    *'''<''': less than
    *'''<=''': less than or equal to
    *'''>''': greater than
    *'''>=''': greater than or equal to


    === Mathematical Operators ===
    === Mathematical Operators ===
    The following mathematical operators can be used with numerical types:
    * '''+'''
    * '''-'''
    * '''*'''
    * '''/'''


    === Boolean Operators ===
    === Boolean Operators ===


    === Matching Operators ===
    The following boolean operators are supported:
     
    * '''and'''
    * '''or'''
    * '''not'''
     
    === String Matching Operators ===
     
    The string matching operators all return a boolean value, indicating success or failure.
     
    String comparisons are done using the following operators:
     
    *'''==''': equality, case sensitive
    *'''=~''': equality, case insensitive
    *'''!=''': inequality, case sensitive
    *'''!~''': inequality, case insensitive
     
    Sub-string matching can be accomplished by using the following operators:
     
    * '''~''': contains, e.g. "'Bar' ~ 'FooBarBaz'" is true
    * '''~~''': contains with case insensitive matching, e.g. "'Bar' ~~ 'FoobarBaz'" is true
     
     
    Sub-sequence matching can be done using these operators (since 5.49):
     
    * '''subseq''': sub-sequence of, e.g. "'FBB' subseq 'FooBarBaz'" is true
    * '''~subseq''': case insensitive sub-sequence of, e.g. "'fbb' ~subseq 'FooBarBaz'" is true
     
    A sub-sequence match is like a sub-string match except the characters do not have to be contiguous. For example 'ct' is a sub-sequence of 'cat' but not a sub-string. 'at' is both a sub-string and sub-sequence of 'cat'. All sub-strings are sub-sequences.
     
    This is useful if you want to support a fuzzier search, say for instance you are searching for '''LibreOffice 6.0 Writer''', after typing '''libre''' you see a list of all the LibreOffice apps, to narrow down that list you only need to add '''write''' (so the search term is '''librewrite''') instead of typing out the entire app name until a distinguishing letter is reached. It's also useful to allow the user to forget to type some characters.
     
     
    Some properties, such as MimeTypes and ServiceTypes, are lists of strings. These lists can be searched using the following operators:
     
    * '''in''': the list contains the string, e.g. "'MyApp/Plugin' in ServiceTypes'"
    * '''~in''': the list contains the string, with case insensitive matching
    * '''subin''': the list contains the string as a substring of one of the entries, e.g. "'Plugin' subin ServiceTypes'"
    * '''~subin''': the list contains the string as a substring of one of the entries, with case insensitive matching
     
    == Command line tool ==
    <pre>
    ktraderclient5 --mimetype <var>mimetype</var> --servicetype <var>servicetype</var> --constraint <var>constraint</var>
    </pre>


    == Query Examples ==
    For example to query dolphin:


    == Working With the Matches ==
    <pre>
    ktraderclient5 --servicetype Application --constraint "DesktopEntryName == 'org.kde.dolphin'"
    </pre>

    Latest revision as of 11:35, 29 April 2019


    Finding Services Using Trader Queries
    Tutorial Series   Services
    Previous   Introduction to the Services Framework
    What's Next   Creating and Loading Plugins Using KService
    Further Reading   n/a


    Abstract

    It is often desirable to be able to find specific types of services or services with specific features or designations. KDE provides a simple yet powerful query language to accomplish this called the KTrader Query Language.

    A Tale of Two Traders

    KDE provides two classes that act as "traders". A trader takes a query and returns a set of services that match those constraints. There is one trader for plugins and other add-ons: KServiceTypeTrader, and one for mimetypes: KMimetypeTrader. Characteristics for both are similar: they have same syntax for querying, offer a singleton pattern accessor, return KService::Ptrs, as well as other similarities. So while this tutorial concentrates primarily on the KServiceTypeTrader, much of the content is applicable to the mimetype trader as well.

    Service Types

    KServiceTypeTrader is used to locate individual components such as application plugins, screensavers, and control panels that are registered with the system. The primary concept used here, is that of the "service type". Each set of services has a unique service type, which makes it very easy to locate the sort of component needed.

    This means that, each kind of application plugin is uniquely namespaced within the set of all services. So, it is trivial to locate plugins for a given application, without having to worry about getting another application's plugin in the list.

    Examples of service types include:

    • KParts/ReadWritePart
    • KTextEditor/Document
    • ScreenSaver
    • TerminalEmulator
    • UserAgentStrings
    • ThumbCreator
    • KDevelop/Plugin

    There is no limit to the number of service types that a given application may use or register. Of course, service types are not limited to plugins and may be used for any sort of data component.

    Creating new service types is covered in the next tutorial of this series: Creating and Loading Plugins Using KService

    Basic KServiceTypeTrader Usage

    The service trader is always accessed via the self() singleton accessor. With the KServiceTypeTrader in hand, we can then do one of three things:

    • query: query for a list of services ordered according to the user's preferences (if any)
    • defaultOffers: request all services, unsorted
    • preferredService: request the preferred service of a given type

    The code to do this is very straight forward:

    KService::List services;
    KServiceTypeTrader* trader = KServiceTypeTrader::self();
    
    services = trader->query("KParts/ReadWritePart");
    foreach (KService::Ptr service, services) {
        kDebug() << "read write part" << service->name();
    }
    
    services = trader->defaultOffers("ThumbCreator");
    if (services.isEmpty()) {
        kDebug() << "no services found for ThumbCreator!";
    }
    
    KService::Ptr service = trader->preferredService("KDevelop/Plugin");
    if (!service) {
        kDebug() << "no preferred service found for KDevelop/Plugin";
    }
    

    In each case zero or more services are returned that are now usable for locating, describing and loading the item it represents.

    The KTrader Query Language

    The above examples are quite simplistic and are not detailed enough for many application needs. For instance, we may only want to list plugins for a certain category, that are associated with a particular mimetype, or that have a specific plugin name. This is where the query language comes in.

    The query language itself is designed to be human readable and flexible. KServiceTypeTrader::query optionally takes a query, in addition to the service type, and uses that to provide more fine-grained searches. So, for example, we'll modify the earlier example in the following way:

    KService::List services ;
    KServiceTypeTrader* trader = KServiceTypeTrader::self();
    
    QString constraint = "'text/plain' in MimeTypes and "
                         "('KOfficePart' in ServiceTypes or "
                         " 'oasis' ~ [X-KDE-ExtraNativeMimeTypes])";
    services = trader->query("KParts/ReadWritePart", constraint);
    
    foreach (KService::Ptr service, services) {
        kDebug() << "read write part" << service->name();
    }
    

    This code will look for a KPart that is both capable of reading/writing plain text files and is also a KOffice component, or can simply read ODF document formats.

    Errors in queries are reported via debug output to console at runtime.

    Order of Operations

    The query string is evaluated left to right, one section at a time. Sections are divided by boolean operators (see below) or by parentheses ('()'), which serve as grouping characters.

    Literals

    Three types of literals are supported by the KTrader Query Language:

    • strings: character strings, which must be enclosed in single quotes (')
    • booleans: TRUE or FALSE
    • signed integers
    • signed floating point numbers

    Identifiers

    Identifiers in a query string are mapped to entries listed in the service's .desktop file. For example, "Name" is the name of the service, "ServiceTypes" is a list of the service types it supports.

    Identifiers may only contain alphanumeric characters and the '-' character. Identifiers that do not start with an alphabetical character or that contain non-alphanumeric characters must be enclosed in brackets, e.g. [X-KDE-Init].

    There are also three special identifiers:

    • DesktopEntryName stands for the filename of the service desktop entry without its extension. This can be useful to exclude some specific services.
    • DesktopEntryPath stands for the relative or full path to the .desktop file, see KService::desktopEntryPath.
    • Library: a synonym for [X-KDE-Library] in the .desktop file.

    An identifier can be checked for existence with the exist operator, e.g. "exist [X-KDE-Library]". This is especially useful when checking for the value of an identifier with a default value. For example, if MyProp is a property with type boolean, one might write "not exist MyProp or MyProp" to match MyProp with a default of "true".

    QString term = "konq";
    QString query = QString("exist Exec and ((exist Keywords and '%1' ~subin Keywords) or (exist GenericName and '%1' ~~ GenericName) or (exist Name and '%1' ~~ Name))").arg(term);
    KService::List services = KServiceTypeTrader::self()->query("Application", query);
    foreach (KService::Ptr service, services) {
        kDebug() << service->name();
    }
    

    Comparison Operators

    The following comparison operators can be used to compare values of any of the supported data types:

    • ==: equality
    • !=: inequality
    • <: less than
    • <=: less than or equal to
    • >: greater than
    • >=: greater than or equal to

    Mathematical Operators

    The following mathematical operators can be used with numerical types:

    • +
    • -
    • *
    • /

    Boolean Operators

    The following boolean operators are supported:

    • and
    • or
    • not

    String Matching Operators

    The string matching operators all return a boolean value, indicating success or failure.

    String comparisons are done using the following operators:

    • ==: equality, case sensitive
    • =~: equality, case insensitive
    • !=: inequality, case sensitive
    • !~: inequality, case insensitive

    Sub-string matching can be accomplished by using the following operators:

    • ~: contains, e.g. "'Bar' ~ 'FooBarBaz'" is true
    • ~~: contains with case insensitive matching, e.g. "'Bar' ~~ 'FoobarBaz'" is true


    Sub-sequence matching can be done using these operators (since 5.49):

    • subseq: sub-sequence of, e.g. "'FBB' subseq 'FooBarBaz'" is true
    • ~subseq: case insensitive sub-sequence of, e.g. "'fbb' ~subseq 'FooBarBaz'" is true

    A sub-sequence match is like a sub-string match except the characters do not have to be contiguous. For example 'ct' is a sub-sequence of 'cat' but not a sub-string. 'at' is both a sub-string and sub-sequence of 'cat'. All sub-strings are sub-sequences.

    This is useful if you want to support a fuzzier search, say for instance you are searching for LibreOffice 6.0 Writer, after typing libre you see a list of all the LibreOffice apps, to narrow down that list you only need to add write (so the search term is librewrite) instead of typing out the entire app name until a distinguishing letter is reached. It's also useful to allow the user to forget to type some characters.


    Some properties, such as MimeTypes and ServiceTypes, are lists of strings. These lists can be searched using the following operators:

    • in: the list contains the string, e.g. "'MyApp/Plugin' in ServiceTypes'"
    • ~in: the list contains the string, with case insensitive matching
    • subin: the list contains the string as a substring of one of the entries, e.g. "'Plugin' subin ServiceTypes'"
    • ~subin: the list contains the string as a substring of one of the entries, with case insensitive matching

    Command line tool

    ktraderclient5 --mimetype <var>mimetype</var> --servicetype <var>servicetype</var> --constraint <var>constraint</var>
    

    For example to query dolphin:

    ktraderclient5 --servicetype Application --constraint "DesktopEntryName == 'org.kde.dolphin'"