1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
|
<html dir="ltr"><head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<META HTTP-EQUIV="assetid" CONTENT="HV01082269"><META NAME="lcid" CONTENT="1033"><title>Handling Queries</title><link rel="stylesheet" type="text/css" href="office10.css"><script type="text/javascript" language="Javascript" src="ExpCollapse.js"></script><script type="text/javascript" language="JavaScript" src="inline.js"></script></head><body><p id="ExpandAllLine" class="ExpFav"><a href="#" onclick="ExpandAll()" onkeypress="ExpandAll()" class="DropDown"><img id="picHeader" border="0" src="expandtri.gif" alt="Show All"><span id="ExpandAll">Show All</span></a></p><h1>Handling Queries</h1><p>The <b class="bterm">Query</b> method is central to a research service. The <b class="bterm">Research</b> task pane submits the user's query to the <b class="bterm">Query</b> method, along with information about the <b class="bterm">Research</b> task pane, the Microsoft® Office 2003 host application, and other user settings. The <b class="bterm">Query</b> method responds with the query results, which may consist of simple hyperlinks or richly formatted content, and may be enhanced with form controls and actions.</p><h2>Query Web Method</h2><p>The <b class="bterm">Query</b> method receives an incoming string value from the <b class="bterm">Research</b> task pane in the form of an XML document that conforms to the <b class="bterm">Microsoft.Search.Query</b> family of schemas, and returns a string value containing the query results (or an alternate message) in the form of an XML document that conforms to the <b class="bterm">Microsoft.Search.Response</b> family of schemas.</p><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show"><b class="bterm">Query</b> method prototype</a></p><div id="ExpCol" class="collapsed" border="0"><p>Visual Basic .Net</p><pre><code><WebMethod(Description="Query Web Method")> _
Public Function Query(queryXml As String) As String</code></pre><p>C#</p><pre><code>[WebMethod(Description="Query Web Method")]
public string Query(string queryXml)</code></pre><p><b>Important</b> The string input parameter for the <b class="bterm">Query</b> Web method must be named <code>queryXml</code>. This name is also case-sensitive. If you find that the incoming argument is empty while you are testing a research Web service, check the name and case of the parameter in the function header.</p></div><h2>Format of the Query Request and Response</h2><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Format of the query request</a></p><div id="ExpCol" class="collapsed" border="0"><p>The query request and response can contain the following elements and attributes. Optional attributes that are not currently used have been omitted.</p><pre><code><QueryPacket xmlns="urn:Microsoft.Search.Query" revision="" build="">
<Query domain="">
<QueryId/>
<OriginatorId/>
<SupportedFormats>
<Format revision="" build="" />
<Any/>
</SupportedFormats>
<Context>
<QueryText language="" type="" />
<LanguagePreference/>
<Requery>
<RequeryContext>
<Any/> *
</RequeryContext>
<Any/>
</Requery>
<OriginatorContext>
<Any/>
</OriginatorContext>
<Any/>
</Context>
<Range id="">
<ResultType/>
<StartAt/>
<Count/>
<Any/>
</Range>
<Any/> **
</Query>
<Any/>
</QueryPacket></code></pre><p>* Additional query request information from the <b class="bterm">Microsoft.Search.ServiceParameters</b> namespace takes the place of the indicated <b class="bterm">Any</b> element.</p><p>** Additional query request information from the <b class="bterm">Microsoft.Search.Query.Office.Context</b> and <b class="bterm">Microsoft.Search.Query.Office.Keywords</b> namespaces takes the place of the indicated <b class="bterm">Any</b> element.</p><p>For more information, see <a href="rsxsdQueryDocs.htm" id="HV01087676" lcid=" ">Microsoft.Search.Query Schema Documentation</a>. For enumerated constants defined in the Microsoft.Search.Query schema, see <a href="rsReferenceEnums.htm" id="HV01085951" lcid=" ">Enumerations Reference</a>.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Format of the query response</a></p><div id="ExpCol" class="collapsed" border="0"><pre><code><ResponsePacket xmlns="urn:Microsoft.Search.Response"
revision=""
build=""
providerRevision="">
<Response domain="">
<QueryId/>
<Copyright/>
<OriginatorContext>
<Any/>
</OriginatorContext>
<RequeryContext>
<Any/>
</RequeryContext>
<Range id="">
<ResultType/>
<StartAt/>
<Count/>
<TotalAvailable/>
<Results>
<Any/> *
</Results>
<Any/>
</Range>
<Status/>
<DebugErrorMessage/>
<Any/>
</Response>
<Any/>
</ResponsePacket>
</code></pre><p>* Additional query response information from the <b class="bterm">Microsoft.Search.Response.Document</b>, <b class="bterm">Microsoft.Search.Response.Content</b>, and <b class="bterm">Microsoft.Search.Response.Form</b> namespaces takes the place of the indicated <b class="bterm">Any</b> element.</p><p><b>Note</b> The preceding list does not include the <b class="bterm">MustDisplayCount</b> element, which is not used.</p><p>For more information, see <a href="rsxsdResponseDocs.htm" id="HV01087693" lcid=" ">Microsoft.Search.Response Schema Documentation</a>. For enumerated constants defined in the Microsoft.Search.Response schema and related schemas, see <a href="rsReferenceEnums.htm" id="HV01085951" lcid=" ">Enumerations Reference</a>.</p></div><h2>Elements of the Query Request and Response</h2><p>The following tables provide information about some of the more significant elements and attributes in the query request and response.</p><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Common elements in the query request and response</a></p><div id="ExpCol" class="collapsed" border="0"><p>Certain query elements are passed back and forth between the <b class="bterm">Research</b> task pane and the research Web service that it is querying.</p><table><tr><th>Element</th><th>Description</th></tr><tr><td><b class="bterm">domain</b> attribute</td><td>On the <b class="bterm">Query</b> element, identifies the service to query; on the <b class="bterm">Response</b> element, identifies the service providing the results.</td></tr><tr><td><b class="bterm">QueryId</b></td><td>Identifies the query with a globally unique identifier (GUID) initially generated by the <b class="bterm">Research</b> task pane.</td></tr><tr><td><b class="bterm">RequeryContext</b></td><td>Returned by the research service if the user submits a requery, then returned by the <b class="bterm">Research</b> task pane to the server on each subsequent request, to assist in maintaining state.</td></tr><tr><td><b class="bterm">Range</b></td><td>Contains elements such as <b class="bterm">StartAt</b> and <b class="bterm">Count</b> that support paging through results. In the query response, also contains the <b class="bterm">Results</b> element, and provides (through the <b class="bterm">id</b> attribute) for circumstances where a single query may return more than one <b class="bterm">Results</b> node.</td></tr></table></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Unique elements in the query request</a></p><div id="ExpCol" class="collapsed" border="0"><p>The <b class="bterm">QueryText</b> element is the most important element in the query request because it transmits the user's query.</p><table><tr><th>Element</th><th>Description</th></tr><tr><td><b class="bterm">QueryPacket</b></td><td>Must reference the <b class="bterm">Microsoft.Search.Query</b> namespace.</td></tr><tr><td><b class="bterm">Query</b></td><td>Uses the <b class="bterm">domain</b> attribute to indicate which of several services from the same provider to query.</td></tr><tr><td><b class="bterm">OriginatorId</b></td><td>Identifies Microsoft Office 2003. (Always the same GUID.)</td></tr><tr><td><b class="bterm">SupportedFormats</b></td><td>Lists the three namespaces that the <b class="bterm">Research</b> task pane currently accepts in the <b class="bterm">Results</b> element of the query response: <b class="bterm">Microsoft.Search.Response.Document</b>, <b class="bterm">Microsoft.Search.Response.Content</b>, and <b class="bterm">Microsoft.Search.Response.Form</b>.</td></tr><tr><td><b class="bterm">QueryText</b></td><td>Contains the text of the user's query. This element's <b class="bterm">language</b> attribute, along with the subsequent <b class="bterm">LanguagePreference</b> element, may also help determine the results to return.</td></tr></table></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Unique elements in the query response</a></p><div id="ExpCol" class="collapsed" border="0"><p>The <b class="bterm">Results</b> element is the most important element in the query response because it transmits the results of the user's query. Note that the <b class="bterm">Status</b> element is required and that without it the <b class="bterm">Research</b> task pane does not display the results received.</p><table><tr><th>Element</th><th>Description</th></tr><tr><td><b class="bterm">ResponsePacket</b></td><td>Must reference the <b class="bterm">Microsoft.Search.Response</b> namespace.</td></tr><tr><td><b class="bterm">Response</b></td><td>Uses the <b class="bterm">domain</b> attribute to indicate which of several services from the same provider is responding.</td></tr><tr><td><b class="bterm">Results</b></td><td>Contains the results of the user's query, including markup to specify how the <b class="bterm">Research</b> task pane should render the data.</td></tr><tr><td><b class="bterm">Status</b></td><td>Indicates the success or failure of the query. Typically, SUCCESS. For more information, see <a href="rsReferenceEnums.htm" id="HV01085951" lcid=" ">Enumerations Reference</a>.</td></tr></table></div><h2>Other Namespaces Used in the Query Request</h2><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Query family of namespaces</a></p><div id="ExpCol" class="collapsed" border="0"><p>In addition to the <b class="bterm">QueryText</b> element that contains the text of the user's query, and the other elements described earlier in this topic, the query request may include additional information in the following elements and attributes. These elements appear in the query request packet at the locations indicated earlier in the section "Format of the Query request."<ul><li>The <b class="bterm">OfficeContext</b> element from the <b class="bterm">Microsoft.Search.Query.Office.Context</b> namespace contains the user's language settings, preferences (such as parental control), and application information (such as the name and version of the Microsoft Office 2003 host application). The <b class="bterm">ServiceData</b> element contains the value of the <b class="bterm">SourceData</b> registry setting, created when the service was registered, which passes arbitrary information set by the developer with each query to the service.</li><li>The <b class="bterm">Keywords</b> element from the <b class="bterm">Microsoft.Search.Query.Office.Keywords</b> namespace contains the list of words in the query phrase, and the results of stemming and word-breaking of the query phrase, if the components required for these operations are present on the client computer and available to the <b class="bterm">Research</b> task pane. (The availability of stemming and word-breaking components depends on the language and the version of Microsoft Windows®. For example, when you are using the English language with Microsoft Windows 2000, neither stemming nor word-breaking are used; when you are using English with Microsoft Windows XP, only word-breaking is used.)</li><li>The <b class="bterm">ServiceParameters</b> element from the <b class="bterm">Microsoft.Search.Office.ServiceParameters</b> namespace contains the values of form elements in cases where the previous query response displayed a form in the <b class="bterm">Research</b> task pane along with query results. This element appears only in a requery.</li></ul></p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Microsoft.Search.Query.Office.Context namespace</a></p><div id="ExpCol" class="collapsed" border="0"><p>The <b class="bterm">OfficeContext</b> element from the <b class="bterm">Microsoft.Search.Query.Office.Context</b> namespace contains the user's language settings, preferences (such as parental control), and application information (such as the name and version of the Microsoft Office 2003 host application). It also sends the <b class="bterm">SourceData</b> registry value to the service, if this registry setting is present, in the child <b class="bterm">Data</b> element of the <b class="bterm">ServiceData</b> element. The following XML fragment shows the <b class="bterm">OfficeContext</b> element sent to the server along with a typical query issued from the <b class="bterm">Research</b> task pane in Microsoft Office Word 2003.</p><pre><code><OfficeContext xmlns='urn:Microsoft.Search.Query.Office.Context'
revision='1'>
<UserPreferences>
<ParentalControl>false</ParentalControl>
</UserPreferences>
<ServiceData></ServiceData>
<ApplicationContext>
<Name>Microsoft Office Word</Name>
<Version>(11.0.5606)</Version>
<SystemInformation>
<SkuLanguage>en-us</SkuLanguage>
<LanguagePack>en-us</LanguagePack>
<InterfaceLanguage>en-us</InterfaceLanguage>
<Location>US</Location>
</SystemInformation>
</ApplicationContext>
<QueryLanguage>en-us</QueryLanguage>
<KeyboardLanguage>en-us</KeyboardLanguage>
</OfficeContext>
</code></pre><p>The following table lists the possible values for the <b class="bterm">Name</b> element of the <b class="bterm">ApplicationContext</b> section, depending on which application is hosting the <b class="bterm">Research</b> task pane. Note that the values returned by Microsoft Internet Explorer and Microsoft Office Excel 2003 do not match the format returned by most of the other Office applications.</p><table><tr><th>Host Application</th><th>Value of Name Element</th></tr><tr><td>Microsoft Internet Explorer</td><td>Microsoft Office</td></tr><tr><td>Microsoft Office Excel 2003</td><td>Microsoft Excel</td></tr><tr><td>Microsoft Office OneNote 2003</td><td>Microsoft Office OneNote</td></tr><tr><td>Microsoft Office Outlook 2003</td><td>Microsoft Office Outlook</td></tr><tr><td>Microsoft Office PowerPoint 2003</td><td>Microsoft Office PowerPoint</td></tr><tr><td>Microsoft Office Publisher 2003</td><td>Microsoft Office Publisher</td></tr><tr><td>Microsoft Office Visio 2003</td><td>Microsoft Office Visio</td></tr><tr><td>Microsoft Office Word 2003</td><td>Microsoft Office Word</td></tr></table><p>For more information, see <a href="rsxsdQueryOfficeContextDocs.htm" id="HV01087674" lcid=" ">Microsoft.Search.Query.Office.Context Schema Documentation</a>.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Microsoft.Search.Query.Office.Keywords namespace</a></p><div id="ExpCol" class="collapsed" border="0"><p>The <b class="bterm">Keywords</b> element from the <b class="bterm">Microsoft.Search.Query.Office.Keywords</b> namespace contains the list of words in the query phrase, and the results of stemming and word-breaking of the query phrase, if the components required for these operations are present on the client computer and available to the <b class="bterm">Research</b> task pane. (The availability of stemming and word-breaking components depends on the language and the version of Microsoft Windows®. For example, when you are using the English language with Microsoft Windows 2000, neither stemming nor word-breaking are used; when you are using English with Microsoft Windows XP, only word-breaking is used.) The <b class="bterm">Keywords</b> section analyzes only the first 255 characters of the user's query. In cases where the user's entire query phrase does not produce any query results, you may choose to have the research Web service return results for selected keywords instead. The following XML fragment shows the <b class="bterm">Keywords</b> element sent to the server when the user enters the query phrase, "He is calm and level-headed" using English with Microsoft Windows XP.</p><pre><code><Keywords xmlns='urn:Microsoft.Search.Query.Office.Keywords'
revision='1'>
<QueryText>He is calm and level-headed.</QueryText>
<Keyword>
<Word>He</Word>
</Keyword>
<Keyword>
<Word>is</Word>
</Keyword>
<Keyword>
<Word>calm</Word>
</Keyword>
<Keyword>
<Word>and</Word>
</Keyword>
<StartAltPhrase/>
<Keyword>
<Word>level</Word>
</Keyword>
<Keyword>
<Word>headed</Word>
</Keyword>
<StartAltPhrase/>
<Keyword>
<Word>level-headed</Word>
</Keyword>
<EndAltPhrase/>
<EndOfSentence/>
</Keywords></code></pre><p>For more information, see <a href="rsxsdQueryOfficeKeywordsDocs.htm" id="HV01087675" lcid=" ">Microsoft.Search.Query.Office.Keywords Schema Documentation</a>.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Microsoft.Search.Office.ServiceParameters namespace</a></p><div id="ExpCol" class="collapsed" border="0"><p>The <b class="bterm">ServiceParameters</b> element from the <b class="bterm">Microsoft.Search.Office.ServiceParameters</b> namespace contains the values of form elements, in cases where the previous query response displayed a form in the <b class="bterm">Research</b> task pane along with query results. The following XML fragment shows the portion of the initial query response from the <a href="rsSamplesEmail.htm" id="HV01082289" lcid=" ">Email Sample</a> that generates a form. This fragment uses the <b class="bterm">Microsoft.Search.Response.Form</b> namespace (discussed later in this topic) to display a form containing two drop-down lists (named <b class="bterm">SortProperty</b> and <b class="bterm">SortOrder</b>) that allow the user to select a sort field and sort order for the query results. When the user makes a selection in either list, the <b class="bterm">Research</b> task pane submits a requery and returns the form values in the <b class="bterm">ServiceParameters</b> element, as shown in the following XML fragment. (Note that in this sample, the <b class="bterm">Microsoft.Search.Response.Form</b> namespace is registered at the document level with the prefix "f".)</p><pre><code><Results>
<f:Form revision='1'>
<f:Listbox dropdown='true' id='SortProperty'
action='requery'>
<f:Text>Sort by: </f:Text>
<f:Option selected='true' id='CompleteName'>
<f:Text>Full name</f:Text>
</f:Option>
<f:Option selected='false' id='LastName'>
<f:Text>Last name</f:Text>
</f:Option>
<f:Option selected='false' id='FirstName'>
<f:Text>First name</f:Text>
</f:Option>
</f:Listbox>
<f:Listbox dropdown='true' id='SortOrder' action='requery'>
<f:Text>Sort order: </f:Text>
<f:Option selected='true' id='Ascending'>
<f:Text>Ascending</f:Text>
</f:Option>
<f:Option selected='false' id='Descending'>
<f:Text>Descending</f:Text>
</f:Option>
</f:Listbox>
</f:Form>
...
</Results></code></pre><p>The following XML fragment shows the form values from the requery sent back to the server when the user makes a selection in the form elements described in the preceding request. This fragment uses the <b class="bterm">Microsoft.Search.Office.ServiceParameters</b> namespace to identify the form element that triggered the requery (in the <b class="bterm">Action</b> element) and the values of the various form elements (in the <b class="bterm">Parameters</b> section, where an element is created with the ID value of each form element as its name, and the value of each form element as its text).</p><pre><code><Context>
...
<Requery>
<ServiceParameters
xmlns='urn:Microsoft.Search.Office.ServiceParameters'>
<Action>SortProperty</Action>
<Parameters>
<SortProperty>LastName</SortProperty>
<SortOrder>Ascending</SortOrder>
</Parameters>
</ServiceParameters>
</Requery>
</Context>
</code></pre><p><b>Note</b> The <b class="bterm">Parameters</b> list of the <b class="bterm">ServiceParameters</b> section contains only the values of form elements whose values can change. For example, it reports the values of drop-down lists and of text boxes. However, it does not report the values of controls with static values, such as buttons or hyperlinks.</p><p>For more information, see <a href="rsxsdOfficeServiceParametersDocs.htm" id="HV01087677" lcid=" ">Microsoft.Search.Office.ServiceParameters Schema Documentation</a>.</p></div><h2>Other Namespaces Used in the Query Response</h2><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Response family of namespaces</a></p><div id="ExpCol" class="collapsed" border="0"><p>Within the <b class="bterm">Results</b> element, the query response uses elements and attributes from up to three supporting namespaces to display and format the query results, as follows. These elements appear in the query response packet at the location of the placeholder <b class="bterm">Any </b>element within the <b class="bterm">Results</b> element.<ul><li>The <b class="bterm">Document</b> element from the <b class="bterm">Microsoft.Search.Response.Document</b> namespace displays query results as a simple URL, with a title and description, in the familiar format used by many Internet search engines. A list of URLs requires a series of <b class="bterm">Document</b> elements.</li><li>The <b class="bterm">Content</b> element from the <b class="bterm">Microsoft.Search.Response.Content</b> namespace supports a much richer layout and formatting of the query results. This includes support for expandable headings, paragraphs, and images, as well as built-in and custom actions.</li><li>The <b class="bterm">Form</b> element from the <b class="bterm">Microsoft.Search.Response.Form</b> namespce uses typical Web form elements to gather additional query or layout criteria or other information from the user.</li></ul></p><p>The query response can contain any combination of <b class="bterm">Document</b> and <b class="bterm">Content</b> elements, in any order; however, only one <b class="bterm">Form</b> element is supported, and the <b class="bterm">Research</b> task pane always displays a <b class="bterm">Form</b> at the top of (that is, as the first element) the query results.</p><p>As you can see by examining the Microsoft.Search.Response.xsd schema, the query response is independent of the supported formats for query results. This structure facilitates the future extensibility of <b class="bterm">Research</b> task pane options, beyond the three results namespaces currently supported.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show"><b class="bterm">Microsoft.Search.Response.Document</b> namespace</a></p><div id="ExpCol" class="collapsed" border="0"><p>The <b class="bterm">Document</b> element from the <b class="bterm">Microsoft.Search.Response.Document</b> namespace displays query results as a simple list of URLs, with a title and description and optional multimedia elements, in the familiar format used by many Internet search engines. The following XML fragment shows a single <b class="bterm">Document</b> element with an accompanying image.</p><pre><code> <Results>
<Document xmlns="urn:Microsoft.Search.Response.Document">
<Title>Microsoft Web Site</Title>
<Action>
<LinkUrl fileExt="htm">http://www.microsoft.com</LinkUrl>
</Action>
<DisplayUrl>http://www.microsoft.com</DisplayUrl>
<Description>
The home page for the Microsoft Corporation.
</Description>
<Media type="IMAGE">
<SrcUrl>
http://www.microsoft.com/homepage/gif/
bnr-microsoft.gif
</SrcUrl>
<AltText>Microsoft logo</AltText>
</Media>
</Document>
</Results>
</code></pre><p>For more information, see <a href="rsxsdResponseDocumentDocs.htm" id="HV01087690" lcid=" ">Microsoft.Search.Response.Document Schema Documentation</a>. For enumerated constants defined in the Microsoft.Search.Response.Document schema, see <a href="rsReferenceEnums.htm" id="HV01085951" lcid=" ">Enumerations Reference</a>.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show"><b class="bterm">Microsoft.Search.Response.Content</b> namespace</a></p><div id="ExpCol" class="collapsed" border="0"><p>The <b class="bterm">Content</b> element from the <b class="bterm">Microsoft.Search.Response.Content</b> namespace supports much richer layout and formatting of the query results, with support for headings, paragraphs, and images, as well as built-in and custom actions. The following table shows the more commonly used elements in this namespace.</p><table><tr><th>Element</th><th>Description</th></tr><tr><td><b class="bterm">P</b></td><td>Paragraph of text.</td></tr><tr><td><b class="bterm">Char</b></td><td>Formatted string of text. Always contained within another element from the <b class="bterm">Content</b> namespace, <b class="bterm">Char</b> provides a choice of font, as well as the <b class="bterm">bold</b>, <b class="bterm">italic</b>, <b class="bterm">smallcaps</b>, <b class="bterm">underline</b>, <b class="bterm">light</b>, <b class="bterm">superscript</b>, and <b class="bterm">subscript</b> attributes.</td></tr><tr><td><b class="bterm">Tabular</b></td><td>Table of name/value combinations. The <b class="bterm">Tabular</b> element must contain one or more <b class="bterm">Record</b> elements, each with a <b class="bterm">Name</b> and a <b class="bterm">Value</b> element of its own.</td></tr><tr><td><b class="bterm">Image</b></td><td>Path to an image to be displayed in the <b class="bterm">Research</b> task pane as a part of the result.</td></tr><tr><td><b class="bterm">Heading</b></td><td>Heading for a section that can be expanded to display more information.</td></tr><tr><td><b class="bterm">Hyperlink</b></td><td>Typical link.</td></tr><tr><td><b class="bterm">HorizontalRule</b></td><td>Separator line.</td></tr><tr><td><b class="bterm">Line</b></td><td>Element used to force controls to display on the same line when possible.</td></tr><tr><td><b class="bterm">NewQuery</b></td><td>Hyperlink that, when clicked, issues a new call to the <b class="bterm">Query</b> method of the research service. The term to be queried is specified as an attribute of the <b class="bterm">NewQuery</b> element.</td></tr></table><p> The following XML fragment shows the formatted output of a simple test research Web service, including a heading, a separator line, and formatted text within paragraphs.</p><pre><code><Results>
<Content xmlns="urn:Microsoft.Search.Response.Content">
<P>Hello world!</P>
<HorizontalRule />
<Heading>
<Text>Features of the Research Task Pane</Text>
</Heading>
<P>Return a list of links.</P>
<P>Return richly formatted content.</P>
<P>Display a <Char bold="true">form</Char>.</P>
</Content>
</Results>
</code></pre><p>For additional examples of the use of the <b class="bterm">Microsoft.Search.Response.Content</b> namespace, review the sample research services included with this SDK. For an example of the Tabular control, see "Adding Simple Actions" in <a href="rsBuildingActionsWithSmartTags.htm" id="HV01082270" lcid=" ">Adding Actions to Query Results</a>.</p><p>For more information, see <a href="rsxsdResponseContentDocs.htm" id="HV01087688" lcid=" ">Microsoft.Search.Response.Content Schema Documentation</a> and <a href="rsBuildingActionsWithSmartTags.htm" id="HV01082270" lcid=" ">Adding Actions to Query Results</a>. For enumerated constants defined in the Microsoft.Search.Response.Content schema, see <a href="rsReferenceEnums.htm" id="HV01085951" lcid=" ">Enumerations Reference</a>.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show"><b class="bterm">Microsoft.Search.Response.Form</b> namespace</a></p><div id="ExpCol" class="collapsed" border="0"><p>The <b class="bterm">Form</b> element from the <b class="bterm">Microsoft.Search.Response.Form</b> namespace uses typical Web form elements to gather additional query or layout criteria or other information from the user. The following XML fragment shows the portion of the initial query response from the <a href="rsSamplesEmail.htm" id="HV01082289" lcid=" ">Email Sample</a> that generates a form containing two drop-down lists (named <b class="bterm">SortProperty</b> and <b class="bterm">SortOrder</b>) that allow the user to select a sort field and sort order for the query results. When the user makes a selection in either list, the <b class="bterm">Research</b> task pane submits a requery and returns the form values in the <b class="bterm">ServiceParameters</b> element, as shown earlier in this topic. (Note that in this sample the <b class="bterm">Microsoft.Search.Response.Form</b> namespace is registered at the document level with the prefix "f".)</p><pre><code><Results>
<f:Form revision='1'>
<f:Listbox dropdown='true' id='SortProperty'
action='requery'>
<f:Text>Sort by: </f:Text>
<f:Option selected='true' id='CompleteName'>
<f:Text>Full name</f:Text>
</f:Option>
<f:Option selected='false' id='LastName'>
<f:Text>Last name</f:Text>
</f:Option>
<f:Option selected='false' id='FirstName'>
<f:Text>First name</f:Text>
</f:Option>
</f:Listbox>
<f:Listbox dropdown='true' id='SortOrder' action='requery'>
<f:Text>Sort order: </f:Text>
<f:Option selected='true' id='Ascending'>
<f:Text>Ascending</f:Text>
</f:Option>
<f:Option selected='false' id='Descending'>
<f:Text>Descending</f:Text>
</f:Option>
</f:Listbox>
</f:Form>
...
</Results></code></pre><p>You can also use a form in the <b class="bterm">Research</b> task pane to gather user credentials for a service that requires authentication. For an example, see "Implementing ASP.NET Forms Authentication" in <a href="rsAuthenticationOptions.htm" id="HV01082332" lcid=" ">Authenticating Research Service Users</a>.</p><p>For more information, see <a href="rsxsdResponseFormDocs.htm" id="HV01087691" lcid=" ">Microsoft.Search.Response.Form Schema Documentation</a>. For enumerated constants defined in the Microsoft.Search.Response.Form schema, see <a href="rsReferenceEnums.htm" id="HV01085951" lcid=" ">Enumerations Reference</a>.</p></div><h2>Additional Implementation Details</h2><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Including custom data with every query request</a></p><div id="ExpCol" class="collapsed" border="0"><p>When a provider registers a service on the user's computer, the provider has the option of storing an arbitrary string of data that the <b class="bterm">Research</b> task pane returns to the service with every subsequent query request from that user on that computer. This feature uses the following schema elements and settings:</p><ul><li>In the registration response, the provider initially sends this arbitrary string of data in the <b class="bterm">Data</b> element. For more information, see <a href="rsRegistrationInterface.htm" id="HV01082272" lcid=" ">Handling Registration Requests</a>.</li><li>The <b class="bterm">Research</b> task pane stores the string of data in the <b class="bterm">SourceData</b> registry setting for the service. For more information, see <a href="rsregServiceSettings.htm" id="HV01083007" lcid=" ">Service Registry Settings</a>.</li><li>In every query request, the <b class="bterm">Research</b> task pane returns the string of data to the service within the <b class="bterm">OfficeContext</b> element, in the <b class="bterm">Data</b> element in the <b class="bterm">ServiceData</b> section. For more information, see "Microsoft.Search.Query.Office.Context" earlier in this topic.</li></ul></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Querying multiple services from the same provider</a></p><div id="ExpCol" class="collapsed" border="0"><p> When a user directs a query to multiple services offered by the same provider, the query request contains multiple <b class="bterm">Query</b> elements in which the <b class="bterm">domain</b> attribute identifies the target service by its GUID ID value. The research service must build a response that contains an equal number of <b class="bterm">Response</b> elements, which likewise identify the responding service through the <b class="bterm">domain</b> attribute.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Requerying</a></p><div id="ExpCol" class="collapsed" border="0"><p> A requery can be launched from a Form control that appears with the results of a previous query, or from a "Next" link when the query results span multiple pages. The requery causes an "update in place" of the <b class="bterm">Research</b> task pane; that is, only the content that changes is replaced with new results. In most other respects, a requery is very similar to any other query; however, additional data is available to the research Web service in the <b class="bterm">RequeryContext</b> element to help the service maintain state information. The <b class="bterm">RequeryContext</b> element is like a lightweight cookie that the server can include in the query response after the first requery. The client then passes the same element and data back to the server with each subsequent requery.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Parental control and filtering query results</a></p><div id="ExpCol" class="collapsed" border="0"><p>When parental control is enabled from the <b class="bterm">Parental Control</b> button of the <b class="bterm">Research Options</b> dialog box, the user cannot query services that do not support parental control (that is, the filtering of query results).</p><p> When the value of <b class="bterm">ParentalControl</b> in the query request is <b class="bterm">true</b> (indicating that the user has requested content filtering), and the service identified itself at registration as supporting parental control, the service is expected to filter inappropriate content out of the query results before returning the results to the user. The <b class="bterm">ParentalControl</b> query request element is defined in the <b class="bterm">Microsoft.Search.Query.Office.Context</b> namespace.</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Recognizing the limitations of the <b class="bterm">Research</b> task pane user interface</a></p><div id="ExpCol" class="collapsed" border="0"><p> Although the <b class="bterm">Research</b> task pane is similar to an embedded browser, it does not have the flexibility of a full-fledged browser. You cannot set the background color, you have limited control over the layout of text and images, and you cannot add client-side script. You also have to learn to make the most of limited screen real estate. You are dealing with an area that is typically 100-200 pixels wide. Therefore, you have to economize in choosing the information you present and its layout and formatting. In some ways, you can compare this to formatting information for a Pocket PC, as the two user interfaces share a similar form factor.
</p></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Updating and removing services</a></p><div id="ExpCol" class="collapsed" border="0"><p> The <b class="bterm">providerRevision</b> attribute of the top-level <b class="bterm">ResponsePacket</b> element in the query response can be used to prompt the user to update (or remove) the service. For more information, see <a href="rsUpdating.htm" id="HV01082282" lcid=" ">Updating and Removing Services</a>.</p></div><h2>Walkthrough: Sample Query Request, Response, and Code</h2><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Sample query request</a></p><div id="ExpCol" class="collapsed" border="0"><p>The following sample query request submits the query "test" to a simple research service. The query includes elements from the <b class="bterm">Microsoft.Search.Query.Office.Context</b> and the <b class="bterm">Microsoft.Search.Query.Office.Keywords</b> namespaces. Since the user is not submitting a form in this case, the query request does not include elements from the <b class="bterm">Microsoft.Search.Office.ServiceParameters</b> namespace. The fixed <b class="bterm">OriginatorID</b> value identifies Microsoft Office 2003.</p><pre><code><QueryPacket xmlns='urn:Microsoft.Search.Query'
revision='1'
build='(11.0.5606)' >
<Query domain='{41F27485-961F-4EA1-82F1-7623E55DE293}'>
<QueryId>
{D0FF4E60-85A5-40CF-B067-8757FB063FB1}
</QueryId>
<OriginatorId>
{F6FF7BE0-F39C-4ddc-A7D0-09A4C6C647A5}
</OriginatorId>
<SupportedFormats>
<Format revision='1'>
urn:Microsoft.Search.Response.Document:Document
</Format>
<Format revision='1'>
urn:Microsoft.Search.Response.Content:Content
</Format>
<Format revision='1'>
urn:Microsoft.Search.Response.Form:Form
</Format>
</SupportedFormats>
<Context>
<QueryText type='STRING' language='en-us' >
test
</QueryText>
<LanguagePreference>en-us</LanguagePreference>
<Requery></Requery>
</Context>
<Range id='result'></Range>
<OfficeContext
xmlns='urn:Microsoft.Search.Query.Office.Context'
revision='1'>
<UserPreferences>
<ParentalControl>false</ParentalControl>
</UserPreferences>
<ServiceData></ServiceData>
<ApplicationContext>
<Name>Microsoft Office Word</Name>
<Version>(11.0.5606)</Version>
<SystemInformation>
<SkuLanguage>en-us</SkuLanguage>
<LanguagePack>en-us</LanguagePack>
<InterfaceLanguage>en-us</InterfaceLanguage>
<Location>US</Location>
</SystemInformation>
</ApplicationContext>
<QueryLanguage>en-us</QueryLanguage>
<KeyboardLanguage>en-us</KeyboardLanguage>
</OfficeContext>
<Keywords xmlns='urn:Microsoft.Search.Query.Office.Keywords'
revision='1'>
<QueryText>test</QueryText>
<Keyword>
<Word>test</Word>
</Keyword>
</Keywords>
</Query>
</QueryPacket></code></pre></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Sample query response</a></p><div id="ExpCol" class="collapsed" border="0"><p><p><b>Important</b> The query response packet that you build must reference the <b class="bterm">Microsoft.Search.Response</b> namespace on the response's top-level <b class="bterm">ResponsePacket</b> element, as shown in the following example.</p></p><p>The following sample query response comes from a fictititious "Hello World Test Research Services" provider that provides a single service named "Hello World Test Research Service in VB." The response contains a hyperlink that uses elements from the <b class="bterm">Microsoft.Search.Response.Document</b> namespace, and formatted content that uses elements from the <b class="bterm">Microsoft.Search.Response.Content</b> namespace.</p><pre><code><?xml version="1.0"?>
<ResponsePacket providerRevision="1"
xmlns="urn:Microsoft.Search.Response">
<Response domain="{41F27485-961F-4EA1-82F1-7623E55DE293}">
<QueryID>{7333D51C-1636-4BA5-AD04-EE7FB60145F4}</QueryID>
<Range>
<Results>
<Document xmlns=
"urn:Microsoft.Search.Response.Document">
<Title>Microsoft Web Site</Title>
<Action>
<LinkUrl fileExt="htm">
http://www.microsoft.com
</LinkUrl>
</Action>
<DisplayUrl>http://www.microsoft.com</DisplayUrl>
<Description>
The home page for the Microsoft Corporation.
</Description>
</Document>
<Content xmlns=
"urn:Microsoft.Search.Response.Content">
<HorizontalRule />
<P>Hello world!</P>
<HorizontalRule />
<Heading>
<Text>
Features of the Research Task Pane
</Text>
</Heading>
<P>Return a list of links.</P>
<P>Return richly formatted content.</P>
<P>Display a <Char bold="true">form</Char>.</P>
</Content>
</Results>
</Range>
<Status>SUCCESS</Status>
</Response>
</ResponsePacket></code></pre></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Sample query response code</a></p><div id="ExpCol" class="collapsed" border="0"><p>The following <b class="bterm">Query</b> Web method code generated the preceding query response. This code uses a private method named SavePacket (shown in <a href="rsResearchWS.htm" id="HV01084670" lcid=" ">Building a Research Web Service</a>) to write the request and response packets to a file for further analysis.</p><pre><code><WebMethod(Description:="The Query method executes the requested" & _
" query and returns the results to the Research task pane.")> _
Public Function Query(ByVal queryXml As String) As String
' Save the Query Request packet for viewing.
SavePacket(queryXml, "qryrequest.xml")
' Extract values we need from the Query Request
Dim xmlQuery As XmlDocument = New XmlDocument
xmlQuery.LoadXml(queryXml)
Dim nm As XmlNamespaceManager = _
New XmlNamespaceManager(xmlQuery.NameTable)
nm.AddNamespace("msq", "urn:Microsoft.Search.Query")
Dim domain As String = _
xmlQuery.SelectSingleNode("/msq:QueryPacket/msq:Query", nm) _
.Attributes.GetNamedItem("domain").Value
Dim queryId As String = _
xmlQuery.SelectSingleNode( _
"/msq:QueryPacket/msq:Query/msq:QueryId", nm).InnerText
xmlQuery = Nothing
Dim qryResponseStream As MemoryStream = New MemoryStream
Dim qryResponseWriter As XmlTextWriter
qryResponseWriter = New XmlTextWriter(qryResponseStream, Nothing)
With qryResponseWriter
' Format the output for easy viewing.
.Formatting = Formatting.Indented
' Compose the Query Response packet.
.WriteStartDocument()
.WriteStartElement("ResponsePacket", _
"urn:Microsoft.Search.Response")
' The providerRevision attribute can be
' used to update the service.
.WriteAttributeString("providerRevision", "1")
.WriteStartElement("Response")
' The domain attribute identifies the service
' that executed the query.
.WriteAttributeString("domain", domain)
.WriteElementString("QueryID", queryId)
.WriteStartElement("Range")
.WriteStartElement("Results")
' Begin Document element
.WriteStartElement("Document", _
"urn:Microsoft.Search.Response.Document")
.WriteElementString("Title", "Microsoft Web Site")
.WriteStartElement("Action")
.WriteStartElement("LinkUrl")
.WriteAttributeString("fileExt", "htm")
.WriteString("http://www.microsoft.com")
.WriteEndElement() ' LinkUrl
.WriteEndElement() ' Action
.WriteElementString("DisplayUrl", "http://www.microsoft.com")
.WriteElementString("Description", _
"The home page for the Microsoft Corporation.")
' Include an image
.WriteStartElement("Media")
.WriteAttributeString("type", "IMAGE")
.WriteElementString("SrcUrl", _
"http://www.microsoft.com/ _
homepage/gif/bnr-microsoft.gif")
.WriteElementString("AltText", "Microsoft logo")
.WriteEndElement() ' Media
.WriteEndElement() ' Document
' End Document element
' Begin Content element
.WriteStartElement("Content", _
"urn:Microsoft.Search.Response.Content")
.WriteStartElement("HorizontalRule")
.WriteEndElement() 'Horizontal rule
.WriteElementString("P", "Hello world!")
.WriteStartElement("HorizontalRule")
.WriteEndElement() 'Horizontal rule
.WriteStartElement("Heading")
.WriteElementString("Text", _
"Features of the Research Task Pane")
.WriteEndElement() 'Heading
.WriteElementString("P", "Return a list of links.")
.WriteElementString("P", "Return richly formatted content.")
.WriteStartElement("P")
.WriteString("Display a ")
.WriteStartElement("Char")
.WriteAttributeString("bold", "true")
.WriteString("form")
.WriteEndElement() ' Char
.WriteString(".")
.WriteEndElement() ' P
.WriteEndElement() ' Content
' End Content element
' Finish up.
.WriteEndElement() ' Results
.WriteEndElement() ' Range
.WriteElementString("Status", "SUCCESS")
.WriteEndElement() ' Response
.WriteEndElement() ' ResponsePacket
.WriteEndDocument()
End With
qryResponseWriter.Flush()
' Move the results into a string.
qryResponseStream.Position = 0
Dim qryResponseReader As StreamReader = _
New StreamReader(qryResponseStream)
Dim qryResponsePacket As String = qryResponseReader.ReadToEnd()
' Save and return the Query Response packet.
SavePacket(qryResponsePacket, "qryresponse.xml")
Return qryResponsePacket
End Function
</code></pre></div><center><a href="XMLSchemaCopyright_HV01147162.htm">©2003-2004 Microsoft Corporation. All rights reserved.</a>
Permission to copy, display and distribute this document is available at: <a
href="http://r.office.microsoft.com/r/rlidAWSContentRedir?AssetID=XT010988631033&CTT=11&Origin=HV011232471033"
target="_new">http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp</a></center></body></html>
|
