1# Copyright (C) 2003-2007  Robey Pointer <robeypointer@gmail.com>
2#
3# This file is part of paramiko.
4#
5# Paramiko is free software; you can redistribute it and/or modify it under the
6# terms of the GNU Lesser General Public License as published by the Free
7# Software Foundation; either version 2.1 of the License, or (at your option)
8# any later version.
9#
10# Paramiko is distributed in the hope that it will be useful, but WITHOUT ANY
11# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
12# A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
13# details.
14#
15# You should have received a copy of the GNU Lesser General Public License
16# along with Paramiko; if not, write to the Free Software Foundation, Inc.,
17# 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.
18
19"""
20Abstraction of an SFTP file handle (for server mode).
21"""
22
23import os
24from paramiko.sftp import SFTP_OP_UNSUPPORTED, SFTP_OK
25from paramiko.util import ClosingContextManager
26
27
28class SFTPHandle(ClosingContextManager):
29    """
30    Abstract object representing a handle to an open file (or folder) in an
31    SFTP server implementation.  Each handle has a string representation used
32    by the client to refer to the underlying file.
33
34    Server implementations can (and should) subclass SFTPHandle to implement
35    features of a file handle, like `stat` or `chattr`.
36
37    Instances of this class may be used as context managers.
38    """
39
40    def __init__(self, flags=0):
41        """
42        Create a new file handle representing a local file being served over
43        SFTP.  If ``flags`` is passed in, it's used to determine if the file
44        is open in append mode.
45
46        :param int flags: optional flags as passed to
47            `.SFTPServerInterface.open`
48        """
49        self.__flags = flags
50        self.__name = None
51        # only for handles to folders:
52        self.__files = {}
53        self.__tell = None
54
55    def close(self):
56        """
57        When a client closes a file, this method is called on the handle.
58        Normally you would use this method to close the underlying OS level
59        file object(s).
60
61        The default implementation checks for attributes on ``self`` named
62        ``readfile`` and/or ``writefile``, and if either or both are present,
63        their ``close()`` methods are called.  This means that if you are
64        using the default implementations of `read` and `write`, this
65        method's default implementation should be fine also.
66        """
67        readfile = getattr(self, "readfile", None)
68        if readfile is not None:
69            readfile.close()
70        writefile = getattr(self, "writefile", None)
71        if writefile is not None:
72            writefile.close()
73
74    def read(self, offset, length):
75        """
76        Read up to ``length`` bytes from this file, starting at position
77        ``offset``.  The offset may be a Python long, since SFTP allows it
78        to be 64 bits.
79
80        If the end of the file has been reached, this method may return an
81        empty string to signify EOF, or it may also return ``SFTP_EOF``.
82
83        The default implementation checks for an attribute on ``self`` named
84        ``readfile``, and if present, performs the read operation on the Python
85        file-like object found there.  (This is meant as a time saver for the
86        common case where you are wrapping a Python file object.)
87
88        :param offset: position in the file to start reading from.
89        :param int length: number of bytes to attempt to read.
90        :return: data read from the file, or an SFTP error code, as a `str`.
91        """
92        readfile = getattr(self, "readfile", None)
93        if readfile is None:
94            return SFTP_OP_UNSUPPORTED
95        try:
96            if self.__tell is None:
97                self.__tell = readfile.tell()
98            if offset != self.__tell:
99                readfile.seek(offset)
100                self.__tell = offset
101            data = readfile.read(length)
102        except IOError as e:
103            self.__tell = None
104            return SFTPServer.convert_errno(e.errno)
105        self.__tell += len(data)
106        return data
107
108    def write(self, offset, data):
109        """
110        Write ``data`` into this file at position ``offset``.  Extending the
111        file past its original end is expected.  Unlike Python's normal
112        ``write()`` methods, this method cannot do a partial write: it must
113        write all of ``data`` or else return an error.
114
115        The default implementation checks for an attribute on ``self`` named
116        ``writefile``, and if present, performs the write operation on the
117        Python file-like object found there.  The attribute is named
118        differently from ``readfile`` to make it easy to implement read-only
119        (or write-only) files, but if both attributes are present, they should
120        refer to the same file.
121
122        :param offset: position in the file to start reading from.
123        :param str data: data to write into the file.
124        :return: an SFTP error code like ``SFTP_OK``.
125        """
126        writefile = getattr(self, "writefile", None)
127        if writefile is None:
128            return SFTP_OP_UNSUPPORTED
129        try:
130            # in append mode, don't care about seeking
131            if (self.__flags & os.O_APPEND) == 0:
132                if self.__tell is None:
133                    self.__tell = writefile.tell()
134                if offset != self.__tell:
135                    writefile.seek(offset)
136                    self.__tell = offset
137            writefile.write(data)
138            writefile.flush()
139        except IOError as e:
140            self.__tell = None
141            return SFTPServer.convert_errno(e.errno)
142        if self.__tell is not None:
143            self.__tell += len(data)
144        return SFTP_OK
145
146    def stat(self):
147        """
148        Return an `.SFTPAttributes` object referring to this open file, or an
149        error code.  This is equivalent to `.SFTPServerInterface.stat`, except
150        it's called on an open file instead of a path.
151
152        :return:
153            an attributes object for the given file, or an SFTP error code
154            (like ``SFTP_PERMISSION_DENIED``).
155        :rtype: `.SFTPAttributes` or error code
156        """
157        return SFTP_OP_UNSUPPORTED
158
159    def chattr(self, attr):
160        """
161        Change the attributes of this file.  The ``attr`` object will contain
162        only those fields provided by the client in its request, so you should
163        check for the presence of fields before using them.
164
165        :param .SFTPAttributes attr: the attributes to change on this file.
166        :return: an `int` error code like ``SFTP_OK``.
167        """
168        return SFTP_OP_UNSUPPORTED
169
170    # ...internals...
171
172    def _set_files(self, files):
173        """
174        Used by the SFTP server code to cache a directory listing.  (In
175        the SFTP protocol, listing a directory is a multi-stage process
176        requiring a temporary handle.)
177        """
178        self.__files = files
179
180    def _get_next_files(self):
181        """
182        Used by the SFTP server code to retrieve a cached directory
183        listing.
184        """
185        fnlist = self.__files[:16]
186        self.__files = self.__files[16:]
187        return fnlist
188
189    def _get_name(self):
190        return self.__name
191
192    def _set_name(self, name):
193        self.__name = name
194
195
196from paramiko.sftp_server import SFTPServer
197