diff --git a/src/Docker.DotNet/Endpoints/IContainerOperations.cs b/src/Docker.DotNet/Endpoints/IContainerOperations.cs index 9bd0cd36f..d4f3692f8 100644 --- a/src/Docker.DotNet/Endpoints/IContainerOperations.cs +++ b/src/Docker.DotNet/Endpoints/IContainerOperations.cs @@ -7,436 +7,405 @@ namespace Docker.DotNet { + /// + /// Provides operations relating to Docker containers. + /// public interface IContainerOperations { /// - /// List containers. + /// Returns a list of containers. /// - /// - /// docker ps - /// docker container ls - /// - /// HTTP GET /containers/json - /// - /// 200 - No error. - /// 400 - Bad parameter. - /// 500 - Server error. - /// + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a list of objects, which represent the containers found. + /// The corresponding commands in the Docker CLI are docker ps and docker container ls. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task> ListContainersAsync(ContainersListParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Create a container + /// Creates a new container from an image. /// - /// - /// docker container create - /// - /// HTTP POST /containers/create - /// - /// 201 - Container created successfully. - /// 400 - Bad parameter. - /// 404 - No such container. - /// 406 - Impossible to attach. - /// 409 - Conflict. - /// 500 - Server error. - /// + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which provides information about the newly-created container. + /// The corresponding command in the Docker CLI is docker container create. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid, there was a conflict with another container, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task CreateContainerAsync(CreateContainerParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Inspect a container. - /// - /// Return low-level information about a container. + /// Retrieves low-level information about a container. /// - /// - /// docker inspect - /// docker container inspect - /// - /// HTTP GET /containers/(id)/json - /// - /// 200 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which holds details about the container. + /// The corresponding commands in the Docker CLI are docker inspect and docker container inspect. + /// No such container was found. + /// One or more of the inputs was . + /// the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task InspectContainerAsync(string id, CancellationToken cancellationToken = default(CancellationToken)); /// - /// List processes running inside a container. - /// - /// On Unix systems, this is done by running the {ps} command. The endpoint is not supported on Windows. + /// Retrieves a list of processes running within the container. /// - /// - /// docker top - /// docker container top - /// - /// HTTP GET /containers/(id)/top - /// - /// 200 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which holds information about the processes. + /// This operation is not supported on Windows, because the underlying API does not support it. + ///
The corresponding commands in the Docker CLI are docker top and docker container top. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task ListProcessesAsync(string id, ContainerListProcessesParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Get container logs. - /// - /// Get {stdout} and {stderr} logs from a container. - /// Note: This endpoint works only for containers with the {json-file} or {journald} logging driver. + /// Gets stdout and stderr logs from a container created with a TTY. /// - /// - /// docker logs - /// docker container logs - /// - /// HTTP GET /containers/(id)/logs - /// - /// 101 - Logs returned as a stream. - /// 200 - Logs returned as a string in response body. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which provides the log information. + /// This method works only for containers with the json-file or journald logging driver. + ///
The corresponding commands in the Docker CLI are docker logs and docker container logs. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. [Obsolete("The stream returned by this method won't be demultiplexed properly if the container was created without a TTY. Use GetContainerLogsAsync(string, bool, ContainerLogsParameters, CancellationToken) instead")] Task GetContainerLogsAsync(string id, ContainerLogsParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Gets the logs from a container. - /// This method is only suited for containers created with a TTY. For containers created without a TTY, use - /// instead. + /// Gets stdout and stderr logs from a container that was created with a TTY. /// - /// ID or name of the container. - /// The parameters used to retrieve the logs. - /// A token used to cancel this operation. - /// - /// The class that will receive the log lines. - /// Every reported string represents one log line, with its terminating newline removed. - /// - /// A Task that will complete once all log lines have been read, or once the container has exited if Follow is set to . + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// Provides a callback for reporting log entries as they're read. Every reported string represents one log line, with its terminating newline removed. + /// A that will complete once all log lines have been read, or once the container has exited if Follow is set to . + /// This method is only suited for containers created with a TTY. For containers created without a TTY, use + /// instead. + ///
+ /// The corresponding commands in the Docker CLI are docker inspect and docker container inspect. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task GetContainerLogsAsync(string id, ContainerLogsParameters parameters, CancellationToken cancellationToken, IProgress progress); /// - /// Gets the stdout and stderr logs from a container. - /// This endpoint works only for containers with the json-file or journald logging driver. + /// Gets stdout and stderr logs from a container. /// - /// ID or name of the container. - /// If the container was created with a TTY or not. If , the returned stream is multiplexed. - /// The parameters used to retrieve the logs. - /// A token used to cancel this operation. - /// A stream with the retrieved logs. If the container wasn't created with a TTY, this stream is multiplexed. + /// The ID or name of the container. + /// Indicates whether the container was created with a TTY. If , the returned stream is multiplexed. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which provides the log information. + /// If the container wasn't created with a TTY, this stream is multiplexed. + /// The corresponding commands in the Docker CLI are docker inspect and docker container inspect. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task GetContainerLogsAsync(string id, bool tty, ContainerLogsParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Get changes on a container's filesystem. - /// - /// Returns which files in a container's filesystem have been added, deleted, or modified. The {Kind} of modification can be one of: - /// 0: Modified - /// 1: Added - /// 2: Deleted + /// Reports which files in a container's filesystem have been added, deleted, or modified. /// - /// - /// HTTP GET /containers/(id)/changes - /// - /// 200 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a list of objects. Each object corresponds to a single changed file. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task> InspectChangesAsync(string id, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Export a container. - /// - /// Export the contents of a container as a tarball. + /// Exports the contents of a container as a tarball. /// - /// - /// docker export - /// docker container export - /// - /// HTTP GET /containers/(id)/export - /// - /// 200 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which can be read to obtain the bytes of the tarball. + /// The corresponding commands in the Docker CLI are docker export and docker container export. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task ExportContainerAsync(string id, CancellationToken cancellationToken = default(CancellationToken)); + /// + /// Retrieves a live, raw stream of the container's resource usage statistics. + /// + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which can be used to read the frames of statistics. For details + /// on the format, refer to the Docker Engine API documentation. + /// + /// The corresponding commands in the Docker CLI are docker stats and docker container stats. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. [Obsolete("Use 'Task GetContainerStatsAsync(string id, ContainerStatsParameters parameters, CancellationToken cancellationToken, IProgress progress)'")] Task GetContainerStatsAsync(string id, ContainerStatsParameters parameters, CancellationToken cancellationToken); /// - /// Get container stats based on resource usage. - /// - /// This endpoint returns a live stream of a container's resource usage statistics. - /// The {precpu_stats} is the CPU statistic of last read, which is used for calculating the CPU usage percentage. It is not the same as the - /// {cpu_stats} field. + /// Retrieves a live, raw stream of the container's resource usage statistics. /// - /// - /// docker stats - /// docker container stats - /// - /// HTTP GET /containers/(id)/stats - /// - /// 200 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// Provides a callback to trigger whenever a new frame of statistics is available. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the stream has been established. + /// The corresponding commands in the Docker CLI are docker stats and docker container stats. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task GetContainerStatsAsync(string id, ContainerStatsParameters parameters, IProgress progress, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Resize a container TTY. - /// - /// Resize the TTY for a container. You must restart the container for the size to take effect. + /// Resizes a container's TTY. /// - /// - /// HTTP POST /containers/(id)/resize - /// - /// 200 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the operation is complete. + /// You must restart the container for the change to take effect. + /// + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task ResizeContainerTtyAsync(string id, ContainerResizeParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Start a container. + /// Starts a container. /// - /// - /// docker start - /// docker container start - /// - /// HTTP POST /containers/(id)/start - /// - /// 204 - No error. - /// 304 - Container already started. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a value indicating whether the container was successfully started. + /// This method does not report an error if the container is already started. + ///
The corresponding commands in the Docker CLI are docker start and docker container start. + /// + /// + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task StartContainerAsync(string id, ContainerStartParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Stop a container. + /// Stops a container. /// - /// - /// docker stop - /// docker container stop - /// - /// HTTP POST /containers/(id)/stop - /// - /// 204 - No error. - /// 304 - Container already stopped. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a value indicating whether the container was successfully stopped. + /// This method does not report an error if the container is already stopped. + ///
The corresponding commands in the Docker CLI are docker stop and docker container stop. + /// + /// + /// + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task StopContainerAsync(string id, ContainerStopParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Restart a container. + /// Stops and then restarts a container. /// - /// - /// docker restart - /// docker container restart - /// - /// HTTP POST /containers/(id)/restart - /// - /// 204 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the operation is complete. + /// The corresponding commands in the Docker CLI are docker restart and docker container restart. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task RestartContainerAsync(string id, ContainerRestartParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Kill a container. - /// - /// Send a POSIX signal to a container, defaulting to killing to the container. + /// Sends a POSIX signal to a container--typically to kill it. /// - /// - /// docker kill - /// docker container kill - /// - /// HTTP POST /containers/(id)/kill - /// - /// 204 - No error. - /// 304 - Container already started. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the operation is complete. + /// The corresponding commands in the Docker CLI are docker kill and docker container kill. + /// No such container was found. + /// + /// + /// One or more of the inputs was . + /// The container was not running, the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task KillContainerAsync(string id, ContainerKillParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Rename a container + /// Changes the name of a container. /// - /// - /// HTTP POST /containers/{id}/rename - /// - /// 204 - No error. - /// 404 - No such container. - /// 409 - Name already in use. - /// 500 - Server error. - /// - /// ID or name of the container. - /// New name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the operation is complete. + /// No such container was found. + /// One or more of the inputs was . + /// The name is already in use, the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task RenameContainerAsync(string id, ContainerRenameParameters parameters, CancellationToken cancellationToken); /// - /// Pause a container. - /// - /// Uses the cgroups freezer to suspend all processes in a container. - /// - /// Traditionally, when suspending a process the {SIGSTOP} signal is used, which is observable by the process being suspended. - /// With the cgroups freezer the process is unaware, and unable to capture, that it is being suspended, and subsequently resumed. + /// Suspends a container. /// + /// The ID or name of the container. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the operation is complete. /// - /// docker pause - /// docker container pause - /// - /// HTTP POST /containers/(id)/pause - /// - /// 204 - No error. - /// 404 - No such container. - /// 500 - Server error. + /// This uses the freeze cgroup to suspend all processes in the container. The processes are unaware that they are being + /// suspended (e.g., they cannot capture a SIGSTOP signal). /// - /// ID or name of the container. + /// The corresponding commands in the Docker CLI are docker pause and docker container pause. + /// + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task PauseContainerAsync(string id, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Unpause a container. - /// - /// Resume a container which has been paused. + /// Resumes a container that was suspended. /// - /// - /// docker unpause - /// docker container unpause - /// - /// HTTP POST /containers/(id)/unpause - /// - /// 204 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the operation is complete. + /// The corresponding commands in the Docker CLI are docker unpause and docker container unpause. + /// + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task UnpauseContainerAsync(string id, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Attach to a container. + /// Attaches to a container to read its output and send it input. /// - /// - /// docker attach - /// docker container attach - /// - /// HTTP POST /containers/(id)/attach - /// - /// 204 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. - /// Is this a TTY stream. + /// The ID or name of the container. + /// Indicates whether the stream is a TTY stream. When , stdout and stderr are + /// combined into a single, undifferentiated stream. When , the stream is multiplexed. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which contains the + /// container's stdout and stderr content and which can be used to write to the container's stdin. + /// The format of the stream various, in part by the parameter's value. See the + /// Docker Engine API reference for details on + /// the format. + /// The corresponding commands in the Docker CLI are docker attach and docker container attach. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The transport is unsuitable for the operation. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task AttachContainerAsync(string id, bool tty, ContainerAttachParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); // TODO: Attach Web Socket /// - /// Wait for a container. - /// - /// Block until a container stops, then returns the exit code. + /// Waits for a container to stop. /// - /// - /// docker wait - /// docker container wait - /// - /// HTTP POST /containers/(id)/wait - /// - /// 204 - No error. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a when the container has + /// stopped. + /// The corresponding commands in the Docker CLI are docker wait and docker container wait. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task WaitContainerAsync(string id, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Remove a container. + /// Deletes a container. /// - /// - /// docker rm - /// docker container rm - /// - /// HTTP DELETE /containers/(id) - /// - /// 204 - No error. - /// 400 - Bad parameter. - /// 404 - No such container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the container has been removed. + /// The corresponding commands in the Docker CLI are docker rm and docker container rm. + /// No such container was found. + /// One or more of the inputs was . + /// There is a conflict, the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task RemoveContainerAsync(string id, ContainerRemoveParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Get information about files in a container - /// - /// -OR- - /// - /// Get an archive of a filestream resource in a container. + /// Gets information about the filesystem in a container. This may be either a listing of files or a complete + /// representation of the filesystem. /// - /// - /// HTTP HEAD /containers/(id)/archive - /// HTTP GET /containers/(id)/archive - /// - /// 204 - No error. - /// 400 - Bad parameter. - /// 404 - Container or path does not exist. - /// 500 - Server error. - /// - /// ID or name of the container. - /// If True will only return file information. If False will return the tarball stream. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// If , the method will only return file information; otherwise, it will return a + /// stream of the filesystem as a tarball. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which holds + /// either the files or a if the tarball. + /// No such container was found, or the path does not exist. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task GetArchiveFromContainerAsync(string id, GetArchiveFromContainerParameters parameters, bool statOnly, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Extract an archive of files or folders to a directory in a container. - /// - /// Upload a tar archive to be extracted to a path in the filesystem of container id. + /// Extracts a tar archive into a container's filesystem. /// - /// - /// HTTP PUT /containers/(id)/archive - /// - /// 204 - The content was extracted successfully. - /// 400 - Bad parameter. - /// 403 - Permission denied, the volume or container rootfs is marked as read-only. - /// 404 - No such container or path does not exist inside the container. - /// 500 - Server error. - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// A readable stream containing the tarball. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves when the operation completes. + /// No such container was found, or the path does not exist inside the container. + /// One or more of the inputs was . + /// Permission is denied (the volume or container rootfs is marked read-only), + /// the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task ExtractArchiveToContainerAsync(string id, ContainerPathStatParameters parameters, Stream stream, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Delete stopped containers + /// Deletes stopped containers. /// - /// - /// HTTP POST /containers/prune - /// - /// 200 - No error. - /// 500 - Server error. - /// + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which details which containers + /// were removed. + /// The corresponding command in the Docker CLI is docker container prune. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task PruneContainersAsync(ContainersPruneParameters parameters = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Update configuration of a container. + /// Changes configuration options of a container without recreating it. /// - /// - /// docker update - /// - /// HTTP POST /containers/(id)/update - /// - /// 200 - No error. - /// 400 - Bad parameter. - /// 404 - No such container. - /// 500 - Server error - /// - /// ID or name of the container. + /// The ID or name of the container. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// A that resolves to a , which provides updated + /// information about the container. + /// The corresponding command in the Docker CLI is docker update. + /// No such container was found. + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task UpdateContainerAsync(string id, ContainerUpdateParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); } } diff --git a/src/Docker.DotNet/Endpoints/IImageOperations.cs b/src/Docker.DotNet/Endpoints/IImageOperations.cs index 87a82a9d1..628bdf24d 100644 --- a/src/Docker.DotNet/Endpoints/IImageOperations.cs +++ b/src/Docker.DotNet/Endpoints/IImageOperations.cs @@ -10,308 +10,284 @@ namespace Docker.DotNet public interface IImageOperations { /// - /// List Images. - /// - /// Returns a list of images on the server. Not that it uses a different, smaller representation - /// of an image than inspecting a single image. + /// Retrieves a list of the images on the server. /// + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker images - /// docker image ls - /// - /// HTTP GET /images/json - /// - /// 200 - Summary image data for the images matching the query. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker images and docker image ls. /// + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task> ListImagesAsync(ImagesListParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Build an image. - /// - /// Build an image from a tar archive with a {Dockerfile} in it. - /// - /// The {Dockerfile } specifies how the image is built from the tar archive. It is typically in the - /// archive's root, but can be at a different path or have a different name by specifying the {dockerfile} + /// Builds an image from a tar archive that contains a Dockerfile. + /// + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. + /// + /// The Dockerfile specifies how the image is built from the tar archive. It is typically in the + /// archive's root, but can be at a different path or have a different name by setting the dockerfile /// parameter. See the Dockerfile reference for more information. - /// - /// The Docker daemon performs a preliminary validation of the {Dockerfile} before starting the build, + ///
+ /// The Docker daemon performs a preliminary validation of the Dockerfile before starting the build, /// and returns an error if the syntax is incorrect. After that, each instruction is run one-by-one until /// the ID of the new image is output. - /// + ///
/// The build is canceled if the client drops the connection by quitting or being killed. - /// - /// - /// docker build - /// docker image build - /// - /// HTTP POST /build - /// - /// 204 - No error. - /// 500 - Server error. + ///
+ /// The equivalent commands in the Docker CLI are docker build and docker image build. /// + /// One or more of the inputs was . + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task BuildImageFromDockerfileAsync(Stream contents, ImageBuildParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Create an image. - /// - /// Create an image by either pulling it from a registry or importing it. + /// Creates an image by either pulling it from a registry or importing it. /// + /// Specifics of how to perform the operation. + /// Information for authenticating with the registry. + /// Provides a delegate the receives progress updates while the operation is underway. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker pull - /// docker image pull - /// - /// 200 - No error. - /// 404 - Repository does not exist or no read access. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker pull and docker image pull. + /// One or more of the inputs was . + /// The repository does not exist, the repository only allows read access for the + /// current auth status, the input is invalid, or the daemon experienced an error. /// + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task CreateImageAsync(ImagesCreateParameters parameters, AuthConfig authConfig, IProgress progress, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Create an image. - /// - /// Create an image by either pulling it from a registry or importing it. + /// Creates an image by either pulling it from a registry or importing it. /// + /// Specifics of how to perform the operation. + /// Information for authenticating with the registry. + /// Additional headers to include in the HTTP request to the registry. + /// Provides a delegate the receives progress updates while the operation is underway. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker pull - /// docker image pull - /// - /// 200 - No error. - /// 404 - Repository does not exist or no read access. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker pull and docker image pull. + /// One or more of the inputs was . + /// The repository does not exist, the repository only allows read access for the + /// current auth status, the input is invalid, or the daemon experienced an error. /// + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task CreateImageAsync(ImagesCreateParameters parameters, AuthConfig authConfig, IDictionary headers, IProgress progress, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Create an image. - /// - /// Create an image by either pulling it from a registry or importing it. + /// Creates an image by importing it from a stream. /// + /// Specifics of how to perform the operation. + /// A readable stream that contains the image to import. + /// Information for authenticating with the registry. + /// Provides a delegate the receives progress updates while the operation is underway. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker pull - /// docker image pull - /// docker import - /// - /// HTTP POST /images/create - /// - /// 200 - No error. - /// 404 - Repository does not exist or no read access. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker pull, docker image pull, and docker import. + /// One or more of the inputs was . + /// The repository does not exist, the repository only allows read access for the + /// current auth status, the input is invalid, or the daemon experienced an error. /// + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task CreateImageAsync(ImagesCreateParameters parameters, Stream imageStream, AuthConfig authConfig, IProgress progress, CancellationToken cancellationToken = default(CancellationToken)); - + /// - /// Create an image. - /// - /// Create an image by either pulling it from a registry or importing it. + /// Creates an image by importing it from a stream. /// + /// Specifics of how to perform the operation. + /// A readable stream that contains the image to import. + /// Information for authenticating with the registry. + /// Additional headers to include in the HTTP request to the registry. + /// Provides a delegate the receives progress updates while the operation is underway. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker pull - /// docker image pull - /// docker import - /// - /// HTTP POST /images/create - /// - /// 200 - No error. - /// 404 - Repository does not exist or no read access. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker pull, docker image pull, and docker import. + /// One or more of the inputs was . + /// The repository does not exist, the repository only allows read access for the + /// current auth status, the input is invalid, or the daemon experienced an error. /// + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task CreateImageAsync(ImagesCreateParameters parameters, Stream imageStream, AuthConfig authConfig, IDictionary headers, IProgress progress, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Inspect an image. - /// - /// Return low-level information about an image. + /// Retrieves low-level information about an image. /// + /// An image name or ID. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker inspect - /// docker image inspect - /// - /// HTTP GET /images/{name}/json - /// - /// 200 - No error. - /// 404 - No such image. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker inspect and docker image inspect. /// - /// Image name or id. + /// One or more of the inputs was . + /// No such image was found. + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task InspectImageAsync(string name, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Get the history of an image. - /// - /// Return parent layers of an image. + /// Gets the "history" (parent layers) of an image. /// + /// An image name or ID. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker history - /// docker image history - /// - /// HTTP GET /images/{name}/history - /// - /// 200 - No error. - /// 404 - No such image. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker history and docker image history. /// - /// Image name or id. + /// One or more of the inputs was . + /// No such image was found. + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task> GetImageHistoryAsync(string name, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Push an image. - /// - /// Push an image to a registry. - /// + /// Pushes an image to a registry. + /// + /// An image name or ID. + /// Specifics of how to perform the operation. + /// Information for authenticating with the registry. + /// Provides a delegate the receives progress updates while the operation is underway. + /// When triggered, the operation will stop at the next available time, if possible. + /// /// If you wish to push an image on to a private registry, that image must already have a tag which /// references that registry. For example {registry.example.com/myimage:latest}. - /// + ///
/// The push is cancelled if the HTTP connection is closed. - /// - /// - /// docker push - /// docker image push - /// - /// HTTP POST /images/{name}/push - /// - /// 200 - No error. - /// 404 - No such image. - /// 500 - Server error. + ///
+ /// The equivalent commands in the Docker CLI are docker push and docker image push. /// - /// Image name or id. + /// One or more of the inputs was . + /// No such image was found. + /// The input is invalid or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task PushImageAsync(string name, ImagePushParameters parameters, AuthConfig authConfig, IProgress progress, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Tag an image. - /// - /// Tag an image so that it becomes part of a registry. + /// Tags an image so that it becomes part of a registry. /// + /// An image name or ID. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker tag - /// docker image tag - /// - /// HTTP POST /images/{name}/tag - /// - /// 201 - No error. - /// 400 - Bad parameter. - /// 404 - No such image. - /// 409 - Conflict. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker tag and docker image tag. /// /// Image name or id. + /// One or more of the inputs was . + /// No such image was found. + /// There was a conflict, or the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task TagImageAsync(string name, ImageTagParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Remove an image. - /// - /// Remove an image, along with any untagged parent images that were referenced by that image. - /// - /// Images can't be removed if they have descendant images, are being used by a running container - /// or are being used by a build. + /// Removes an image, along with any untagged parent images that were referenced by that image. /// + /// An image name or ID. + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker inspect - /// docker image inspect - /// - /// HTTP DELETE /images/{name} - /// - /// 200 - No error. - /// 404 - No such image. - /// 500 - Server error. + /// Images can't be removed if they have descendant images, are being used by a running container, + /// or are being used by a build. + ///
+ /// The equivalent commands in the Docker CLI are docker inspect and docker image inspect. /// /// Image name or id. + /// One or more of the inputs was . + /// No such image was found. + /// There was a conflict, or the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task>> DeleteImageAsync(string name, ImageDeleteParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Search images - /// - /// Search for an image on Docker Hub. + /// Searchs for an image on Docker Hub. /// + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker search - /// - /// HTTP GET /images/search - /// - /// 200 - No error. - /// 500 - Server error. + /// The equivalent command in the Docker CLI is docker search. /// + /// One or more of the inputs was . + /// There was a conflict, or the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task> SearchImagesAsync(ImagesSearchParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Delete unused images + /// Deletes unused images. /// + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker rmi - /// - /// HTTP POST /images/prune - /// - /// 200 - No error. - /// 500 - Server error. + /// The equivalent commands in the Docker CLI are docker rmi and docker image rm. /// + /// One or more of the inputs was . + /// There was a conflict, or the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task PruneImagesAsync(ImagesPruneParameters parameters = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Create a new image from a container. /// + /// Specifics of how to perform the operation. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker commit - /// - /// HTTP POST /commit - /// - /// 201 - No error. - /// 404 - No such container. - /// 500 - Server error. + /// The equivalent command in the Docker CLI is docker commit. /// + /// One or more of the inputs was . + /// There was a conflict, or the input is invalid, or the daemon experienced an error. + /// No such container was found. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task CommitContainerChangesAsync(CommitContainerChangesParameters parameters, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Export an image. - /// - /// Get a tarball containing all images and metadata for a repository. + /// Exports an image and its associated metadata as a tarball. /// + /// An image name or ID. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker export - /// - /// HTTP GET /images/{name}/get - /// - /// 200 - No error. - /// 404 - No such image. - /// 500 - Server error. + /// The equivalent command in the Docker CLI is docker export. /// /// Image name or ID. + /// + /// One or more of the inputs was . + /// There was a conflict, or the input is invalid, or the daemon experienced an error. + /// No such image was found. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task SaveImageAsync(string name, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Export several images. - /// - /// Get a tarball containing all images and metadata for several image repositories. - /// - /// For each value of the {names} parameter: if it is a specific name and tag(e.g. {ubuntu:latest}), - /// then only that image(and its parents) are returned; if it is an image ID, similarly only that - /// image (and its parents) are returned and there would be no names referenced in the 'repositories' - /// file for this image ID. - /// - /// For details on the format, see the {export image endpoint}. + /// Exports multiple images and their associated metadata to a single tarball. /// + /// An array of image names and IDs. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker export - /// - /// HTTP GET /images/get - /// - /// 200 - No error. - /// 404 - No such image. - /// 500 - Server error. + /// For each value of the parameter: if it is a specific name and tag (e.g. ubuntu:latest), + /// then only that image (and its parents) are returned; if it is an image ID, similarly only that + /// image (and its parents) are returned and there would be no names referenced in the 'repositories' + /// file for this image ID. + ///
+ /// The equivalent command in the Docker CLI is docker export. /// /// Image names to filter by. + /// + /// One or more of the inputs was . + /// There was a conflict, or the input is invalid, or the daemon experienced an error. + /// No such image was found. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task SaveImagesAsync(string[] names, CancellationToken cancellationToken = default(CancellationToken)); /// /// Loads a set of images and tags into a Docker repository. /// + /// Specifics of how to perform the operation. + /// A readable stream that contains the images and tags to import. + /// Provides a delegate the receives progress updates while the operation is underway. + /// When triggered, the operation will stop at the next available time, if possible. /// - /// docker load - /// - /// HTTP POST /images/load - /// - /// 200 - No error. - /// 500 - Server error. + /// The equivalent command in the Docker CLI is docker load. /// + /// One or more of the inputs was . + /// There was a conflict, or the input is invalid, or the daemon experienced an error. + /// The request failed due to an underlying issue such as network connectivity, DNS failure, server certificate validation or timeout. Task LoadImageAsync(ImageLoadParameters parameters, Stream imageStream, IProgress progress, CancellationToken cancellationToken = default(CancellationToken)); } } \ No newline at end of file