3.1.5.3.12 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 directory.

This request is different from other FrontPage Server Extensions Remote Protocol requests because it receives 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 shown in the following illustration.

Figure 4: Type encoding sequence for POST

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 using the same rules as a normal method request. The REQUEST-NAME-STRING, as specified in [RFC4234], MUST be put documents and it accepts the list of parameters given in the Tokens section that follows. The server SHOULD fail with error code 0x0004000C 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 part 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 part: The server SHOULD parse the DocInfo part as a DOC-INFO-Request (for details, see DOC-INFO-Request (section 2.2.2.2.15)). The next MIME part MUST be a DocData part.

DocData part: A DocData part can 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 part: An End part MUST be ignored by the server. Any subsequent part SHOULD also be considered to be an End part.

Note 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 Put-Option (section 2.2.2.2.18), the server either succeeds in storing all the documents or does 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, then documents in the request before the one that failed MUST be stored, and documents after the one that failed MUST NOT be stored.

Tokens

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

put_option: A set of flags describing the client's requested behavior. For details, see Put-Option.

time_tokens: This parameter uses a VECTOR-TIME. Each time the value that is specified in the time_tokens parameter is checked, in addition to values specified through the vti_timelastmodified metakey and putOption = edit check. If this parameter is sent, it MUST either be empty (which is equivalent to not sending it) or it MUST contain a TIME entry for each document that will be sent in the remainder of the request. In that case, the server SHOULD check this value in addition to the vti_timelastmodified metakey sent in each request.<48>

listFiles: A BOOLEAN value that specifies if the docs return value will be included in the response. The server MUST include the docs return value if, and only if, this parameter is TRUE.

listLinkInfo: See section 3.1.5.3.1.

validateWelcomeNames: For semantics, see section 3.1.5.3.1.

URL

FPAuthorScriptUrl

Return Values

The server can return the error codes 0x00090002, 0x0009000E, and 0x0009000F 2.2.2.2.17.1.

docs: A VECTOR-DOCINFO containing information about the saved documents. This value MUST NOT be included in the response if listFiles is passed as FALSE.

error-index: This INT is only returned 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 DOC-INFO MUST be returned if, and only if, error-index is also returned. This indicates the document URL and metadata for the document that could not be uploaded.