1. Introduction

This document outlines the recommended patterns for consuming a server’s direct file transmission capabilities through the OWIN interface. It depends on OWIN v1.0.0-RC0 (but may work with other versions) and uses the extension key mechanics as outlined in CommonKeys.html.

2. Definitions

SendFile – A server or platform feature that is capable of optimizing the copy of a files contents to the response output.

3. Detection

In order for an application to use SendFile it MUST first detect support for the extension.

3.1 Startup

At startup the server SHOULD specify in the Properties “server.Capabilities” dictionary if SendFile is supported (see the table below). If the application does not see support for SendFile it MAY insert a middleware to add SendFile support.

Key Name	Description
“sendfile.Version”	The string value “1.0” indicating version 1.0 of the OWIN SendFile extension.
“sendfile.Support”	An IDictionary<string, object> containing feature details. This key and value do not need to be present if the dictionary would be empty.
“sendfile.Concurrency”	Placed in the sendfile.Support dictionary, the string value “Overlapped” indicates support for multiple outstanding async operations.

3.2 Per Request

The SendFile capable server or middleware adds the SendFileFunc to the environment dictionary for an application to utilize.

Key Name	Description
“sendfile.SendAsync”	The SendFileFunc provided by the server or middleware for the application to utilize. See Delegate Signature.

4. Delegate Signature

The SendFile Func signature is as follows:

using SendFileFunc =

Func

string, // File Name and path

long, // Initial file offset

long?, // Byte count, null for remainder of file

Task // Complete

5. Consumption

The server or middleware provides the SendFileFunc in the environment dictionary. The consumer checks for its presence and invokes it once for each file range to be sent. Before, after, or in between SendFile operations the consumer MAY also write to the response body stream. If the consumer does write to the response body stream, they SHOULD flush the stream to ensure proper ordering with SendFileFunc invocations. The server or middleware implementing SendFileFunc MUST NOT complete the corresponding Task until it is completely finished accessing the named file. Once complete the application MUST be able to perform any normally allowed operations on the file including rename, modify, append, or delete.

Invoking the SendFileFunc SHOULD result in the response headers being sent if they have not already been, so the consumer MUST complete any necessary headers in advance, including range, content-length, transfer-encoding, etc..

Some implementations MAY permit SendFileFunc to be invoked multiple times before the prior operations have completed. This capability is advertised with the key “sendFile.Concurrency” and value “Overrlapped”.

Middleware that wish to replace, augment, or otherwise intercept SendFileFunc operations MAY do so by replacing the Func in the environment dictionary, possibly creating an invocation chain.

File names and paths SHOULD be absolute disk paths, e.g. “c:\myapp\myfile.ext”. Routing middleware MAY assist in mapping relative URIs or disk paths to absolute disk paths.

Contents