3.1.5.3.20 list documents

The list documents request is used by the client to request a list of files, folders, and sites that is contained in a given folder.

Parameters

service_name: This parameter is deprecated. See service_name in section 3.1.5.3.1.

folderList: The folderList parameter is a METADICT (section 2.2.2.2.11) containing the names of folders as the keys, and the corresponding time stamps of type TIME (section 2.2.2.1.6) for the client's cached metadata for those folders as the values. The client SHOULD send the time stamps for folders' metadata if it has cached this information. If a folder's name and time stamp are missing from the folderList parameter, the server MUST return that folder's contents with all available metadata. Otherwise, the server MUST return all available metadata for only those files, folders, and subsites which have changed since the time stamp recorded in the folderList. For files, folders, and subsites which have not changed, the server SHOULD return an empty METADICT to indicate that the client's cache is still valid. The client MUST interpret an empty METADICT as an indication of validity.

The following example of a value for the folderList parameter requests metadata for all files in the root folders of the site and in the images folders that have a time stamp later than the specified date and time. For other files in these folders, only the file name and an empty METADICT are included in the response. For all other folders within the initialUrl parameter, all available metadata MUST be returned.

 [;TX|06 Apr 2006 20:03:02 -0000;images;TX|05 Apr 2006 20:03:02 -0000]

initialUrl: A URL-STRING (section 2.2.2.2.3) that contains the URL of the folder from which documents are listed. This MUST be a service-relative URL.

listBorders: A BOOLEAN (section 2.2.2.1.3) value that specifies whether the contents of the shared borders folders that contains shared border pages SHOULD be listed. If TRUE, the contents SHOULD be listed; if FALSE, they SHOULD NOT be listed.

listChildWebs: A BOOLEAN value that specifies whether the server response SHOULD include the names of the child site folders in the urldirs return value. If TRUE, and the listFolders parameter is also sent as TRUE, the names SHOULD be included; if FALSE, they SHOULD NOT be included. If the client sends this parameter as TRUE, the client SHOULD also send the listFolders parameter as TRUE. The server SHOULD ignore a TRUE value for this parameter if the listFolders parameter is not also TRUE.

listDerived: A BOOLEAN value that specifies whether the list of files in the derived documents folder SHOULD be included in the response. If TRUE, the list of files SHOULD be included as part of the response; if FALSE, they SHOULD NOT be included.<37>

listExplorerDocs: A BOOLEAN value that specifies whether task-list files (_vti_pvt/_x_todo.htm and _vti_pvt/_x_todoh.htm) are listed. If TRUE, the files MAY be listed. If FALSE, they MUST NOT be listed. Servers SHOULD ignore this value if received.

listFiles: A BOOLEAN value that specifies whether the client requests information about the files in each folder that appears in the response. If TRUE, the server SHOULD include the document_list return value; if FALSE, the server SHOULD exclude the document_list return value. By default, the server SHOULD set this value to TRUE.

listFolders: A BOOLEAN value that specifies whether the server response SHOULD include the names and metadata of folders under the URL specified by the initialUrl parameter. If TRUE, the names and metadata of the folders SHOULD be included; if FALSE, they SHOULD NOT be included. By default, the server SHOULD set this value to TRUE.

listHiddenDocs: A BOOLEAN value that specifies whether hidden documents in a site SHOULD be listed. If TRUE, the documents SHOULD be listed; if FALSE, they SHOULD NOT be listed.

listIncludeParent: A BOOLEAN value that specifies whether an entry for the initialUrl field SHOULD be included in the server response. If TRUE, the entry SHOULD be included; if FALSE, it SHOULD NOT be included.

listLinkInfo: For semantics, see section 3.1.5.3.1. By default, the server SHOULD set this value to TRUE.

listRecurse: A BOOLEAN value that specifies whether the server response SHOULD recursively list the subfolders of folders under the URL specified by the initialUrl parameter. If TRUE, the subfolders SHOULD be listed; if FALSE, they SHOULD NOT be listed. The default value is TRUE unless the client specifies otherwise. If listRecurse is set, all child folders of that folder SHOULD be taken into account; otherwise, only the immediate child folders SHOULD be considered. By default, the server SHOULD set this value to TRUE.

listThickets: A BOOLEAN value that specifies whether thicket supporting files and folders SHOULD be included in the server response. If TRUE, the supporting files and folders SHOULD be included; if FALSE, they SHOULD NOT be included. By default, the server SHOULD set this value to TRUE.

platform: A STRING (section 2.2.2.1.5) that specifies the operating system of the client that controls the listing of any open web bot (custom component). If the field is missing or empty, the server MUST NOT include the bot_list return value in the response. If the field contains data, information about any open web bot on the server MAY be included. This parameter MUST NOT be passed by clients conforming to the FrontPage Server Extensions: Website Management Protocol.

validateWelcomeNames: For semantics, see validateWelcomeNames in section 3.1.5.3.1.

Entry Point

FPAuthorScriptUrl

Return Values

document_list: For semantics, see document_list in section 3.1.5.3.1. The server MUST omit this return value if the listFiles parameter was sent as FALSE. If this value is returned, the server MUST list the names and metadata for the requested set of documents specified by the parameters of the request.

bot_list: A DOCUMENT-LIST-RETURN-TYPE (section 2.2.2.2.13) that MUST NOT be included when the platform parameter is empty (including when the parameter is not sent). Because clients conforming to the FrontPage Server Extensions: Website Management Protocol MUST NOT send this parameter, the server need not support this return value. The server MAY<38> return an empty bot_list if it wants to partially support this value.

urldirs: A VECTOR-URL-DIRECTORY (section 2.2.2.2.16) that contains the names and metadata for the specified folders and root directories of subsites. The server MUST omit this return value if the listFolders parameter was sent as FALSE. If this value is returned, the server MUST enumerate the folders and sites specified by the parameters of the request.