Struct openssh_sftp_client::WriteEnd

pub struct WriteEnd<Buffer, Auxiliary = ()> { /* private fields */ }

It is recommended to create at most one WriteEnd per thread using WriteEnd::clone.

Implementations

impl<Buffer, Auxiliary> WriteEnd<Buffer, Auxiliary>

pub fn new(shared_data: SharedData<Buffer, Auxiliary>) -> Self

pub fn into_shared_data(self) -> SharedData<Buffer, Auxiliary>

impl<Buffer: Send + Sync, Auxiliary> WriteEnd<Buffer, Auxiliary>

pub fn send_open_file_request(
    &mut self,
    id: Id<Buffer>,
    params: OpenFileRequest<'_>
) -> Result<AwaitableHandle<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_close_request(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>
) -> Result<AwaitableStatus<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_read_request(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    offset: u64,
    len: u32,
    buffer: Option<Buffer>
) -> Result<AwaitableData<Buffer>, Error>

• buffer - If set to None or the buffer is not long enough, then crate::Data::AllocatedBox will be returned.

Return crate::Data::Buffer or crate::Data::AllocatedBox if not EOF, otherwise returns crate::Data::Eof.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_remove_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>
) -> Result<AwaitableStatus<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_rename_request(
    &mut self,
    id: Id<Buffer>,
    oldpath: Cow<'_, Path>,
    newpath: Cow<'_, Path>
) -> Result<AwaitableStatus<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_mkdir_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>,
    attrs: FileAttrs
) -> Result<AwaitableStatus<Buffer>, Error>

• attrs - FileAttrs::get_size must be equal to None.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_rmdir_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>
) -> Result<AwaitableStatus<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_opendir_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>
) -> Result<AwaitableHandle<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_readdir_request(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>
) -> Result<AwaitableNameEntries<Buffer>, Error>

Return all entries in the directory specified by the handle, including . and ...

The filename only contains the basename.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_stat_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>
) -> Result<AwaitableAttrs<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_lstat_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>
) -> Result<AwaitableAttrs<Buffer>, Error>

Does not follow symlink

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_fstat_request(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>
) -> Result<AwaitableAttrs<Buffer>, Error>

• handle - Must be opened with FileMode::READ.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_setstat_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>,
    attrs: FileAttrs
) -> Result<AwaitableStatus<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_fsetstat_request(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    attrs: FileAttrs
) -> Result<AwaitableStatus<Buffer>, Error>

• handle - Must be opened with OpenOptions::write set.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_readlink_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>
) -> Result<AwaitableName<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_realpath_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>
) -> Result<AwaitableName<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_symlink_request(
    &mut self,
    id: Id<Buffer>,
    targetpath: Cow<'_, Path>,
    linkpath: Cow<'_, Path>
) -> Result<AwaitableStatus<Buffer>, Error>

Create symlink

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

pub fn send_limits_request(
    &mut self,
    id: Id<Buffer>
) -> Result<AwaitableLimits<Buffer>, Error>

Return limits of the server

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

Precondition

Requires Extensions::limits to be true.

pub fn send_expand_path_request(
    &mut self,
    id: Id<Buffer>,
    path: Cow<'_, Path>
) -> Result<AwaitableName<Buffer>, Error>

This supports canonicalisation of relative paths and those that need tilde-expansion, i.e. “~”, “~/…” and “~user/…”.

These paths are expanded using shell-like rules and the resultant path is canonicalised similarly to WriteEnd::send_realpath_request.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

Precondition

Requires Extensions::expand_path to be true.

pub fn send_fsync_request(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>
) -> Result<AwaitableStatus<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

Precondition

Requires Extensions::fsync to be true.

pub fn send_hardlink_request(
    &mut self,
    id: Id<Buffer>,
    oldpath: Cow<'_, Path>,
    newpath: Cow<'_, Path>
) -> Result<AwaitableStatus<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

Precondition

Requires Extensions::hardlink to be true.

pub fn send_posix_rename_request(
    &mut self,
    id: Id<Buffer>,
    oldpath: Cow<'_, Path>,
    newpath: Cow<'_, Path>
) -> Result<AwaitableStatus<Buffer>, Error>

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

Precondition

Requires Extensions::posix_rename to be true.

impl<Buffer: ToBuffer + Send + Sync + 'static, Auxiliary> WriteEnd<Buffer, Auxiliary>

pub fn send_write_request_buffered(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    offset: u64,
    data: Cow<'_, [u8]>
) -> Result<AwaitableStatus<Buffer>, Error>

Write will extend the file if writing beyond the end of the file.

It is legal to write way beyond the end of the file, the semantics are to write zeroes from the end of the file to the specified offset and then the data.

On most operating systems, such writes do not allocate disk space but instead leave “holes” in the file.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

This function is only suitable for writing small data since it needs to copy the entire data into buffer.

For writing large data, it is recommended to use WriteEnd::send_write_request_direct.

pub fn send_write_request_buffered_vectored(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    offset: u64,
    io_slices: &[IoSlice<'_>]
) -> Result<AwaitableStatus<Buffer>, Error>

Write will extend the file if writing beyond the end of the file.

It is legal to write way beyond the end of the file, the semantics are to write zeroes from the end of the file to the specified offset and then the data.

On most operating systems, such writes do not allocate disk space but instead leave “holes” in the file.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

This function is only suitable for writing small data since it needs to copy the entire data into buffer.

For writing large data, it is recommended to use WriteEnd::send_write_request_direct.

pub fn send_write_request_buffered_vectored2(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    offset: u64,
    bufs: &[&[IoSlice<'_>]]
) -> Result<AwaitableStatus<Buffer>, Error>

Write will extend the file if writing beyond the end of the file.

It is legal to write way beyond the end of the file, the semantics are to write zeroes from the end of the file to the specified offset and then the data.

On most operating systems, such writes do not allocate disk space but instead leave “holes” in the file.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

This function is only suitable for writing small data since it needs to copy the entire data into buffer.

For writing large data, it is recommended to use WriteEnd::send_write_request_direct.

pub fn send_write_request_zero_copy(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    offset: u64,
    data: &[Bytes]
) -> Result<AwaitableStatus<Buffer>, Error>

Write will extend the file if writing beyond the end of the file.

It is legal to write way beyond the end of the file, the semantics are to write zeroes from the end of the file to the specified offset and then the data.

On most operating systems, such writes do not allocate disk space but instead leave “holes” in the file.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

This function is zero-copy.

pub fn send_write_request_zero_copy2(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    offset: u64,
    data_slice: &[&[Bytes]]
) -> Result<AwaitableStatus<Buffer>, Error>

Write will extend the file if writing beyond the end of the file.

It is legal to write way beyond the end of the file, the semantics are to write zeroes from the end of the file to the specified offset and then the data.

On most operating systems, such writes do not allocate disk space but instead leave “holes” in the file.

NOTE that this merely add the request to the buffer, you need to call SharedData::flush to actually send the requests.

This function is zero-copy.

pub async fn send_write_request_direct(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    offset: u64,
    data: &[u8]
) -> Result<AwaitableStatus<Buffer>, Error>

Write will extend the file if writing beyond the end of the file.

It is legal to write way beyond the end of the file, the semantics are to write zeroes from the end of the file to the specified offset and then the data.

On most operating systems, such writes do not allocate disk space but instead leave “holes” in the file.

This function sends write requests directly, without any buffering, thus it is not cancel safe.

Cancel Safety

This function is only cancel safe if the data is no more than 1024 long.

Otherwise it is not cancel safe, dropping the future returned might cause the data to paritaly written, and thus the sftp-server might demonstrate undefined behavior.

pub async fn send_write_request_direct_vectored(
    &mut self,
    id: Id<Buffer>,
    handle: Cow<'_, Handle>,
    offset: u64,
    data: &[IoSlice<'_>]
) -> Result<AwaitableStatus<Buffer>, Error>

Write will extend the file if writing beyond the end of the file.

It is legal to write way beyond the end of the file, the semantics are to write zeroes from the end of the file to the specified offset and then the data.

On most operating systems, such writes do not allocate disk space but instead leave “holes” in the file.

This function sends vectored write requests directly, without any buffering, thus it is not cancel safe.

Cancel Safety

This function is only cancel safe if the data is no more than 1024 long.

Otherwise it is not cancel safe, dropping the future returned might cause the data to paritaly written, and thus the sftp-server might demonstrate undefined behavior.

Methods from Deref<Target = SharedData<Buffer, Auxiliary>>

pub fn strong_count(&self) -> usize

SharedData is a newtype wrapper for Arc<SharedDataInner>, so this function returns how many Arc there are that referred to the shared data.

pub fn get_auxiliary(&self) -> &Auxiliary

pub fn get_auxiliary_mut(&mut self) -> Option<&mut Auxiliary>

pub fn create_response_id(&self) -> Id<Buffer>

Create a useable response id.

pub fn try_reserve_id(&self, new_id_cnt: u32) -> bool

Return true if reserve succeeds, false otherwise.

pub fn reserve_id(&self, new_id_cnt: u32)

Return true if reserve succeeds, false otherwise.

pub async fn try_flush(&self) -> Result<bool, Error>

Flush the write buffer.

If another thread is flushing, then Ok(false) will be returned.

Cancel Safety

This function is only cancel safe if WriteEnd::send_write_request_direct or WriteEnd::send_write_request_direct_vectored is not called when this future is cancelled.

Upon cancel, it might only partially flushed out the data, which can be restarted by another thread.

However, if WriteEnd::send_write_request_direct or WriteEnd::send_write_request_direct_vectored is called, then the write data will be interleaved and thus produce undefined behavior.

pub async fn flush(&self) -> Result<(), Error>

Flush the write buffer.

If another thread is flushing, then this function would wait until the other thread is done.

Cancel Safety

This function is only cancel safe if WriteEnd::send_write_request_direct or WriteEnd::send_write_request_direct_vectored is not called when this future is cancelled.

Upon cancel, it might only partially flushed out the data, which can be restarted by another thread.

However, if WriteEnd::send_write_request_direct or WriteEnd::send_write_request_direct_vectored is called, then the write data will be interleaved and thus produce undefined behavior.

Trait Implementations

impl<Buffer, Auxiliary> Clone for WriteEnd<Buffer, Auxiliary>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Buffer: Debug, Auxiliary: Debug> Debug for WriteEnd<Buffer, Auxiliary>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Buffer, Auxiliary> Deref for WriteEnd<Buffer, Auxiliary>

type Target = SharedData<Buffer, Auxiliary>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<Buffer, Auxiliary> DerefMut for WriteEnd<Buffer, Auxiliary>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.