1# Matching Rules of Explicit Want and Implicit Want 2 3Both explicit Want and implicit Want can be used to match an ability to start based on certain rules. These rules determine how the parameters set in Want match the configuration file declared by the target ability. 4 5## Matching Rules of Explicit Want 6 7 8The table below describes the matching rules of explicit Want. 9 10| Name| Type| Matching Item| Mandatory| Rule Description| 11| -------- | -------- | -------- | -------- | -------- | 12| deviceId | string | Yes| No| If this field is unspecified, only abilities on the local device are matched.| 13| bundleName | string | Yes| Yes| If **abilityName** is specified but **bundleName** is unspecified, the matching fails.| 14| moduleName | string | Yes| No| If this field is unspecified and multiple modules with the same ability name exist in the application, the first ability is matched by default.| 15| abilityName | string | Yes| Yes| To use explicit Want, this field must be specified.| 16| uri | string | No| No| This field is not used for matching. It is passed to the target ability as a parameter.| 17| type | string | No| No| This field is not used for matching. It is passed to the target ability as a parameter.| 18| action | string | No| No| This field is not used for matching. It is passed to the target ability as a parameter.| 19| entities | Array<string> | No| No| This field is not used for matching. It is passed to the target ability as a parameter.| 20| flags | number | No| No| This field is not used for matching and is directly transferred to the system for processing. It is generally used to set runtime information, such as URI data authorization.| 21| parameters | {[key: string]: any} | No| No| This field is not used for matching. It is passed to the target ability as a parameter.| 22 23## Matching Rules for Implicit Want 24 25The table below describes the matching rules of implicit Want. 26 27| Name | Type | Matching Item| Mandatory| Rule Description | 28| ----------- | ------------------------------ | ------ | ---- | ------------------------------------------------------------ | 29| deviceId | string | Yes | No | Implicit invoking is not supported across devices. | 30| abilityName | string | No | No | To use implicit Want, this field must be left unspecified. | 31| bundleName | string | Yes | No | - When only **bundleName** is specified, matching is limited to that application.<br>- When both **bundleName** and **moduleName** are specified, matching is limited to that module in that application.<br>- When only **moduleName** is specified, the setting is invalid.<br> <br>These fields will be used for implicit matching.| 32| moduleName | string | Yes | No | | 33| uri | string | Yes | No | | 34| type | string | Yes | No | | 35| action | string | Yes | No | | 36| entities | Array<string> | Yes | No | | 37| flags | number | No | No | This field is not used for matching and is directly transferred to the system for processing. It is generally used to set runtime information, such as URI data authorization.| 38| parameters | {[key: string]: any} | No | No | This field is not used for matching. It is passed to the target ability as a parameter. | 39 40Get familiar with the following about implicit Want: 41 42 43- The **want** parameter passed by the caller indicates the operation to be performed by the caller. It also provides data and application type restrictions. 44 45- The **skills** field declares the capabilities of the target ability. For details, see [the skills tag](../quick-start/module-configuration-file.md#skills) in the [module.json5 file](../quick-start/module-configuration-file.md). 46 47 48The system matches the **want** parameter (including the **action**, **entities**, **uri**, and **type** attributes) passed by the caller against the **skills** configuration (including the **actions**, **entities**, **uris**, and **type** attributes) of the abilities one by one. When all the four attributes are matched, a dialog box is displayed for users to select a matched application. 49 50 51### Matching Rules of action in the want Parameter 52 53The system matches the [action](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction) attribute in the **want** parameter passed by the caller against **actions** under **skills** of the abilities. 54 55- If **action** in the passed **want** parameter is specified but **actions** under **skills** of an ability is unspecified, the matching fails. 56 57- If **action** in the passed **want** parameter is unspecified but **actions** under **skills** of an ability is specified, the matching is successful. 58 59- If **action** in the passed **want** parameter is specified, and **actions** under **skills** of an ability is specified and contains **action** in the passed **want** parameter, the matching is successful. 60 61- If **action** in the passed **want** parameter is specified, and **actions** under **skills** of an ability is specified but does not contain **action** in the passed **want** parameter, the matching fails. 62 63 **Figure 1** Matching rules of action in the want parameter 64 65  66 67 68### Matching Rules of entities in the want Parameter 69 70The system matches the [entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity) attribute in the **want** parameter passed by the caller against **entities** under **skills** of the abilities. 71 72- If **entities** in the passed **want** parameter is unspecified but **entities** under **skills** of an ability is specified, the matching is successful. 73 74- If **entities** in the passed **want** parameter is unspecified but **entities** under **skills** of an ability is unspecified, the matching is successful. 75 76- If **entities** in the passed **want** parameter is specified but **entities** under **skills** of an ability is unspecified, the matching fails. 77 78- If **entities** in the passed **want** parameter is specified, and **entities** under **skills** of an ability is specified and contains **entities** in the passed **want** parameter, the matching is successful. 79 80- If **entities** in the passed **want** parameter is specified, and **entities** under **skills** of an ability is specified but does not contain **entities** in the passed **want** parameter, the matching fails. 81 82 Figure 2 Matching rule of entities in the want parameter 83 84  85 86 87### Matching Rules of uri and type in the want Parameter 88 89When the **uri** and **type** parameters are specified in the **want** parameter to initiate a component startup request, the system traverses the list of installed components and matches the **uris** array under **skills** of the abilities one by one. If one of the **uris** arrays under **skills** matches the **uri** and **type** in the passed **want**, the matching is successful. 90 91Figure 3 Matching rules when uri and type are specified in the want parameter 92 93 94 95There are four combinations of **uri** and **type** settings. The matching rules are as follows: 96 97- Neither **uri** or **type** is specified in the **want** parameter. 98 - If the **uris** array under **skills** of an ability is unspecified, the matching is successful. 99 - If the **uris** array under **skills** of an ability contains an URI element whose **scheme** and **type** are unspecified, the matching is successful. 100 - In other cases, the matching fails. 101 102- Only **uri** is specified in the **want** parameter. 103 - If the **uris** array under **skills** of an ability is unspecified, the matching fails. 104 - If the **uris** array under **skills** of an ability contains an element whose [uri is matched](#matching-rules-of-uri) and **type** is unspecified, the matching is successful. Otherwise, the matching fails. 105 106- Only **type** is specified in the **want** parameter. 107 - If the **uris** array under **skills** of an ability is unspecified, the matching fails. 108 - If the **uris** array under **skills** of an ability contains an URI element whose **scheme** is unspecified and [type is matched](#matching-rules-of-type), the matching is successful. Otherwise, the matching fails. 109 110- Both **uri** and **type** are specified in the **want** parameter, as shown in Figure 3. 111 - If the **uris** array under **skills** of an ability is unspecified, the matching fails. 112 - If the **uris** array under **skills** of an ability contains an element whose [uri is matched](#matching-rules-of-uri) and [type is matched](#matching-rules-of-type), the matching is successful. Otherwise, the matching fails. 113 114 115To simplify the description, **uri** and **type** passed in the **want** parameter are called **w_uri** and **w_type**, respectively; the **uris** array under **skills** of an ability to match is called **s_uris**; each element in the array is called **s_uri**. Matching is performed from top to bottom. 116 117 118Figure 4 Matching rules of uri and type in the want parameter 119 120 121 122 123### Matching Rules of uri 124 125To simplify the description, **uri** in the passed **want** parameter is called **w_uri**; **uri** under **skills** of an ability to match is called **s_uri**. The matching rules are as follows: 126 127- If **scheme** of **s_uri** is unspecified and **w_uri** is unspecified, the matching is successful. Otherwise, the matching fails. 128 129- If **host** of **s_uri** is unspecified and **scheme** of **w_uri** and **scheme** of **s_uri** are the same, the matching is successful. Otherwise, the matching fails. 130 131- If **path**, **pathStartWith**, and **pathRegex** of **s_uri** are unspecified and **w_uri** and **s_uri** are the same, the matching is successful. Otherwise, the matching fails. 132 133- If **path** of **s_uri** is specified and the **full path expressions** of **w_uri** and **s_uri** are the same, the matching is successful. Otherwise, the matching of **pathStartWith** continues. 134 135- If **pathStartWith** of **s_uri** is specified and **w_uri** contains the prefix expression of **s_uri**, the matching is successful. Otherwise, **pathRegex** matching continues. 136 137- If **pathRegex** of **s_uri** is specified and **w_uri** meets the regular expression of **s_uri**, the matching is successful. Otherwise, the matching fails. 138 139> **NOTE** 140> 141> The **scheme**, **host**, **port**, **path**, **pathStartWith**, and **pathRegex** attributes of **uris** under **skills** of an ability are concatenated. If **path**, **pathStartWith**, and **pathRegex** are declared in sequence, **uris** can be concatenated into the following expressions: 142> 143> - **Full path expression**: `scheme://host:port/path` 144> 145> - **Prefix expression**: `scheme://host:port/pathStartWith` 146> 147> - **Regular expression**: `scheme://host:port/pathRegex` 148 149 150### Matching Rules of type 151 152> **NOTE** 153> 154> The matching rules of **type** described in this section are based on the fact that **type** in the **want** parameter is specified. If **type** is unspecified, follow the [matching rules of uri and type in the want parameter](#matching-rules-of-uri-and-type-in-the-want-parameter). 155 156To simplify the description, **uri** in the passed **want** parameter is called **w_type**, and **type** of **uris** under **skills** of an ability to match is called **s_type**. The matching rules are as follows: 157 158- If **s_type** is unspecified, the matching fails. 159 160- If **s_type** or **w_type** contains the wildcard `*/*`, the matching is successful. 161 162- If the last character of **s_type** is the wildcard `*`, for example, `prefixType/*`, the matching is successful only when **w_type** contains `prefixType/`. 163 164- If the last character of **w_type** is the wildcard `*`, for example, `prefixType/*`, the matching is successful only when **s_type** contains `prefixType/`. 165
