3.1.5.3.26 put documents

The put documents request is used by the client to write multiple files to a site. This request SHOULD be used when a higher level wants to save a document that contains other files (such as graphics) from an application directly to a site folder.

This request is different from other FrontPage Server Extensions: Website Management Protocol requests because it sends multiple streams. The following details show how the server MUST parse the method.

The HTTP POST MUST be a multipart/mixed MIME document. Each part of the POST MUST be one of the following four types: UrlArgs, DocInfo, DocData, or End. These types are defined and scoped to this section; they exist merely to provide convenient names for the concepts.

The request MUST begin with a UrlArgs part. After the first part, each part determines the type of the next part, as illustrated in the following figure.

Figure 3: Type encoding sequence for POST

UrlArgs: The UrlArgs part MUST have a Content-Type of application/x-www-form-urlencoded (as specified in [RFC2616] section 14.17) and MUST be parsed like a normal method request. The REQUEST-NAME-STRING (as specified in [RFC4234] and section 2.2.2.2.4) MUST be "put documents" and it accepts the list of parameters given in the following Parameters section. The server SHOULD fail with a "client-too-old" error if the client is an earlier version than the server supports, just like any other method.

If the next part exists, it MUST be DocInfo with a Content-Type of application/x-www-form-urlencoded (as specified in [RFC2616] section 14.17) or it MUST be End with a Content-Type of text/html.

DocInfo: The server SHOULD parse the DocInfo part as a DOCINFO (for details, see section 2.2.2.2.15). The next MIME part MUST be DocData.

DocData: A DocData part MAY have any Content-Type and MUST be the stream corresponding to the DOCINFO sent in the prior DocInfo MIME part. If the next part exists, it SHOULD be DocInfo if its Content-Type is application/x-www-form-urlencoded (as specified in [RFC2616] section 14.17) or SHOULD be End if its Content-Type is text/html, also specified in [RFC2616].

End: An End part MUST be ignored by the server. Any subsequent part SHOULD also be considered to be an End part.

The server SHOULD accept and ignore a DocInfo/DocData pair if the URL in the DOCINFO is empty. Clients SHOULD avoid doing this because it wastes bandwidth.

If the "atomic" PUT-OPTION-VAL is specified as defined in section 2.2.2.2.18, the server SHOULD either succeed in storing all the documents or not store any of them. If the client does not request the "atomic" option, or if the server does not honor the option, and if the server is unable to store a document, documents in the request before the one that failed MUST be stored, and documents after the one that failed MUST NOT be stored.

Parameters

service_name: This parameter is deprecated. For semantics, see service_name in section 3.1.5.3.1.

listFiles: A BOOLEAN (section 2.2.2.1.3) value that specifies whether the docs return value will be included in the response. The server MUST include the docs return value if this parameter is TRUE.

listLinkInfo: For semantics, see listLinkInfo in section 3.1.5.3.1.

put_option: A set of PUT-OPTION-VAL flags that describe how the operation behaves; see section 2.2.2.2.18 for specific semantics for the options.

time_tokens: A VECTOR-TIME (section 2.2.2.2.1). If this argument is sent, it MUST either be empty (which is equivalent to not sending it) or it MUST contain a TIME (section 2.2.2.1.6) entry for each document that will be sent in the remainder of the request. If this argument contains TIME values, and the put_option argument includes "edit", the server SHOULD check this value when performing the check for modifications, in addition to checking the vti_timelastmodified (section 2.2.2.3.82) metakey sent with the metadata for each document, as described in Put-Options for "edit" in section 2.2.2.2.18.<41>

validateWelcomeNames: For semantics, see validateWelcomeNames in section 3.1.5.3.1.

Entry Point

FPAuthorScriptUrl

Return Values

message: For semantics, see message in section 3.1.5.3.1.

docs: A VECTOR-DOCINFO (section 2.2.2.2.12) that contains information about the saved documents. This value MUST NOT be included in the response if listFiles is passed as FALSE.

error-index: This INT (section 2.2.2.1.2) is returned only in error conditions for a single document rather than the transfer in general (for example, because of a time stamp mismatch, a document exists, or a document is checked out). If present, it MUST be the zero-based index of the document that the server was unable to store.

document: This DOCINFO MUST be returned if, and only if, error-index is also returned. This SHOULD indicate the document URL and metadata for the document that could not be uploaded.