3.1.5.3.1 Common Method Parameters and Return Values

The following parameters and return values are common to many of the methods.

Parameters

apply_opt: An APPLY-OPTION (section 2.2.2.2.36) value that consists of one or more comma-delimited arguments that tell the server to apply a theme, style sheet, or border to an entire site or to one or more documents. An optional argument can request metadata on the object to which the theme, style sheet, or border was applied. This parameter is not required and defaults to no option.

The arguments for this parameter are as follows.

Argument	Action
APPLY-OPT-WEB	Apply the method to the entire site.
APPLY-OPT-PAGE	Apply the method to one or more pages.
APPLY-OPT-RFI	Return meta information for the affected documents.

The APPLY-OPT-WEB and APPLY-OPT-PAGE arguments are effectively mutually exclusive; if the APPLY-OPT-WEB argument is present, any APPLY-OPT-PAGE argument is ignored. If the APPLY-OPT-RFI argument is included, the return value includes the updated metadata for each page that is specified by the url_list parameter.

document_name: A URL-STRING (section 2.2.2.2.3) that specifies the service-relative URL of the document that the request is addressed to.

effective_protocol_version: This parameter is deprecated. Clients conforming to the FrontPage Server Extensions: Website Management Protocol MUST NOT send this parameter. If this parameter is sent by a client, the server SHOULD validate it as a VERSION (section 2.2.2.2.9) but MUST otherwise ignore it. <23>

listLinkInfo: A BOOLEAN (section 2.2.2.1.3) value that specifies whether the server response SHOULD contain information about the links from the current page or pages. If TRUE, the response SHOULD include link information; if FALSE, link information SHOULD be excluded to reduce bandwidth and server processing overhead. Servers MAY ignore this parameter and avoid sending link information for nonconforming clients.<24>

meta_info: A METADICT (section 2.2.2.2.11) that contains all the metadata that is required for the request. Details about the specific metadata returned are provided in the descriptive text for that request.

return_stats: The client MUST NOT send this BOOLEAN value. If the server receives it, the server MUST validate its data type but SHOULD otherwise ignore it. If a server chooses not to ignore it, it MAY return an additional return value that provides details about the cost of the request.<25>

service_name: This parameter is obsolete for all methods except create service (section 3.1.5.3.8), remove service (section 3.1.5.3.32), and rename service (section 3.1.5.3.33), but the client MAY send this URL-STRING that defines the server-relative URL of the site that the request is addressed to. <26>For all methods other than the ones specified, the server MUST ignore it. The URL to which the request is posted MUST be used to determine what site the request is issued against.

url_list: A VECTOR-URL-STRING (section 2.2.2.2.3) list of service-relative URLs that specifies which documents will have the method applied. The client SHOULD omit this parameter or leave it empty to obtain the default server behavior.

validateWelcomeNames: A BOOLEAN value that determines if each item in the file's list of links SHOULD replace links to a folder with links to the welcome page (the default web page) for that folder, if it exists. If TRUE, checking for default pages is done; if FALSE, checking is not done. The server MAY ignore this value.

Return Values

The following are common return values for several methods:

document_list: A DOCUMENT-LIST-RETURN-TYPE (section 2.2.2.2.13) that contains the names and metadata for all the documents and folders specified in the request. Depending on the method, these documents and folders MAY be specified as parameters, or if unspecified, MAY include all the documents and folders in a specified site.

message: A STRING (section 2.2.2.1.5) description of the action taken by the server. This is intended for debugging, and SHOULD be ignored by the client.

meta_info: A METADICT that contains a list of the metadata returned in response to the request. Depending on the method, this METADICT can contain all or only a specified subset of the metadata available for the target of the request, which can be a site, folder, or document, as specified in each method description.

status: A STATUS (section 2.2.2.2.17) that contains a description of the error result, if any. This return value SHOULD be included only for any method that encounters an error during processing. The client MAY display an error message to the user, log the error, or attempt to recover from the error.