git.sesse.net Git - casparcg/blob - SFML-1.6/include/SFML/Network/Ftp.hpp

   1 ////////////////////////////////////////////////////////////\r
   2 //\r
   3 // SFML - Simple and Fast Multimedia Library\r
   4 // Copyright (C) 2007-2009 Laurent Gomila (laurent.gom@gmail.com)\r
   5 //\r
   6 // This software is provided 'as-is', without any express or implied warranty.\r
   7 // In no event will the authors be held liable for any damages arising from the use of this software.\r
   8 //\r
   9 // Permission is granted to anyone to use this software for any purpose,\r
  10 // including commercial applications, and to alter it and redistribute it freely,\r
  11 // subject to the following restrictions:\r
  12 //\r
  13 // 1. The origin of this software must not be misrepresented;\r
  14 //    you must not claim that you wrote the original software.\r
  15 //    If you use this software in a product, an acknowledgment\r
  16 //    in the product documentation would be appreciated but is not required.\r
  17 //\r
  18 // 2. Altered source versions must be plainly marked as such,\r
  19 //    and must not be misrepresented as being the original software.\r
  20 //\r
  21 // 3. This notice may not be removed or altered from any source distribution.\r
  22 //\r
  23 ////////////////////////////////////////////////////////////\r
  24 \r
  25 #ifndef SFML_FTP_HPP\r
  26 #define SFML_FTP_HPP\r
  27 \r
  28 ////////////////////////////////////////////////////////////\r
  29 // Headers\r
  30 ////////////////////////////////////////////////////////////\r
  31 #include <SFML/System/NonCopyable.hpp>\r
  32 #include <SFML/Network/SocketTCP.hpp>\r
  33 #include <string>\r
  34 #include <vector>\r
  35 \r
  36 \r
  37 namespace sf\r
  38 {\r
  39 class IPAddress;\r
  40 \r
  41 ////////////////////////////////////////////////////////////\r
  42 /// This class provides methods for manipulating the FTP\r
  43 /// protocol (described in RFC 959).\r
  44 /// It provides easy access and transfers to remote\r
  45 /// directories and files on a FTP server\r
  46 ////////////////////////////////////////////////////////////\r
  47 class SFML_API Ftp : NonCopyable\r
  48 {\r
  49 public :\r
  50 \r
  51     ////////////////////////////////////////////////////////////\r
  52     /// Enumeration of transfer modes\r
  53     ////////////////////////////////////////////////////////////\r
  54     enum TransferMode\r
  55     {\r
  56         Binary, ///< Binary mode (file is transfered as a sequence of bytes)\r
  57         Ascii,  ///< Text mode using ASCII encoding\r
  58         Ebcdic  ///< Text mode using EBCDIC encoding\r
  59     };\r
  60 \r
  61     ////////////////////////////////////////////////////////////\r
  62     /// This class wraps a FTP response, which is basically :\r
  63     /// - a status code\r
  64     /// - a message\r
  65     ////////////////////////////////////////////////////////////\r
  66     class SFML_API Response\r
  67     {\r
  68     public :\r
  69 \r
  70         ////////////////////////////////////////////////////////////\r
  71         /// Enumerate all the valid status codes returned in\r
  72         /// a FTP response\r
  73         ////////////////////////////////////////////////////////////\r
  74         enum Status\r
  75         {\r
  76             // 1xx: the requested action is being initiated,\r
  77             // expect another reply before proceeding with a new command\r
  78             RestartMarkerReply          = 110, ///< Restart marker reply\r
  79             ServiceReadySoon            = 120, ///< Service ready in N minutes\r
  80             DataConnectionAlreadyOpened = 125, ///< Data connection already opened, transfer starting\r
  81             OpeningDataConnection       = 150, ///< File status ok, about to open data connection\r
  82 \r
  83             // 2xx: the requested action has been successfully completed\r
  84             Ok                    = 200, ///< Command ok\r
  85             PointlessCommand      = 202, ///< Command not implemented\r
  86             SystemStatus          = 211, ///< System status, or system help reply\r
  87             DirectoryStatus       = 212, ///< Directory status\r
  88             FileStatus            = 213, ///< File status\r
  89             HelpMessage           = 214, ///< Help message\r
  90             SystemType            = 215, ///< NAME system type, where NAME is an official system name from the list in the Assigned Numbers document\r
  91             ServiceReady          = 220, ///< Service ready for new user\r
  92             ClosingConnection     = 221, ///< Service closing control connection\r
  93             DataConnectionOpened  = 225, ///< Data connection open, no transfer in progress\r
  94             ClosingDataConnection = 226, ///< Closing data connection, requested file action successful\r
  95             EnteringPassiveMode   = 227, ///< Entering passive mode\r
  96             LoggedIn              = 230, ///< User logged in, proceed. Logged out if appropriate\r
  97             FileActionOk          = 250, ///< Requested file action ok\r
  98             DirectoryOk           = 257, ///< PATHNAME created\r
  99 \r
 100             // 3xx: the command has been accepted, but the requested action\r
 101             // is dormant, pending receipt of further information\r
 102             NeedPassword       = 331, ///< User name ok, need password\r
 103             NeedAccountToLogIn = 332, ///< Need account for login\r
 104             NeedInformation    = 350, ///< Requested file action pending further information\r
 105 \r
 106             // 4xx: the command was not accepted and the requested action did not take place,\r
 107             // but the error condition is temporary and the action may be requested again\r
 108             ServiceUnavailable        = 421, ///< Service not available, closing control connection\r
 109             DataConnectionUnavailable = 425, ///< Can't open data connection\r
 110             TransferAborted           = 426, ///< Connection closed, transfer aborted\r
 111             FileActionAborted         = 450, ///< Requested file action not taken\r
 112             LocalError                = 451, ///< Requested action aborted, local error in processing\r
 113             InsufficientStorageSpace  = 452, ///< Requested action not taken; insufficient storage space in system, file unavailable\r
 114 \r
 115             // 5xx: the command was not accepted and\r
 116             // the requested action did not take place\r
 117             CommandUnknown          = 500, ///< Syntax error, command unrecognized\r
 118             ParametersUnknown       = 501, ///< Syntax error in parameters or arguments\r
 119             CommandNotImplemented   = 502, ///< Command not implemented\r
 120             BadCommandSequence      = 503, ///< Bad sequence of commands\r
 121             ParameterNotImplemented = 504, ///< Command not implemented for that parameter\r
 122             NotLoggedIn             = 530, ///< Not logged in\r
 123             NeedAccountToStore      = 532, ///< Need account for storing files\r
 124             FileUnavailable         = 550, ///< Requested action not taken, file unavailable\r
 125             PageTypeUnknown         = 551, ///< Requested action aborted, page type unknown\r
 126             NotEnoughMemory         = 552, ///< Requested file action aborted, exceeded storage allocation\r
 127             FilenameNotAllowed      = 553, ///< Requested action not taken, file name not allowed\r
 128 \r
 129             // 10xx: SFML custom codes\r
 130             InvalidResponse  = 1000, ///< Response is not a valid FTP one\r
 131             ConnectionFailed = 1001, ///< Connection with server failed\r
 132             ConnectionClosed = 1002, ///< Connection with server closed\r
 133             InvalidFile      = 1003  ///< Invalid file to upload / download\r
 134         };\r
 135 \r
 136         ////////////////////////////////////////////////////////////\r
 137         /// Default constructor\r
 138         ///\r
 139         /// \param Code :    Response status code (InvalidResponse by default)\r
 140         /// \param Message : Response message (empty by default)\r
 141         ///\r
 142         ////////////////////////////////////////////////////////////\r
 143         Response(Status Code = InvalidResponse, const std::string& Message = "");\r
 144 \r
 145         ////////////////////////////////////////////////////////////\r
 146         /// Convenience function to check if the response status code\r
 147         /// means a success\r
 148         ///\r
 149         /// \return True if status is success (code < 400)\r
 150         ///\r
 151         ////////////////////////////////////////////////////////////\r
 152         bool IsOk() const;\r
 153 \r
 154         ////////////////////////////////////////////////////////////\r
 155         /// Get the response status code\r
 156         ///\r
 157         /// \return Status code\r
 158         ///\r
 159         ////////////////////////////////////////////////////////////\r
 160         Status GetStatus() const;\r
 161 \r
 162         ////////////////////////////////////////////////////////////\r
 163         /// Get the full message contained in the response\r
 164         ///\r
 165         /// \return The response message\r
 166         ///\r
 167         ////////////////////////////////////////////////////////////\r
 168         const std::string& GetMessage() const;\r
 169 \r
 170     private :\r
 171 \r
 172         ////////////////////////////////////////////////////////////\r
 173         // Member data\r
 174         ////////////////////////////////////////////////////////////\r
 175         Status      myStatus;  ///< Status code returned from the server\r
 176         std::string myMessage; ///< Last message received from the server\r
 177     };\r
 178 \r
 179     ////////////////////////////////////////////////////////////\r
 180     /// Specialization of FTP response returning a directory\r
 181     ////////////////////////////////////////////////////////////\r
 182     class SFML_API DirectoryResponse : public Response\r
 183     {\r
 184     public :\r
 185 \r
 186         ////////////////////////////////////////////////////////////\r
 187         /// Default constructor\r
 188         ///\r
 189         /// \param Resp : Source response\r
 190         ///\r
 191         ////////////////////////////////////////////////////////////\r
 192         DirectoryResponse(Response Resp);\r
 193 \r
 194         ////////////////////////////////////////////////////////////\r
 195         /// Get the directory returned in the response\r
 196         ///\r
 197         /// \return Directory name\r
 198         ///\r
 199         ////////////////////////////////////////////////////////////\r
 200         const std::string& GetDirectory() const;\r
 201 \r
 202     private :\r
 203 \r
 204         ////////////////////////////////////////////////////////////\r
 205         // Member data\r
 206         ////////////////////////////////////////////////////////////\r
 207         std::string myDirectory; ///< Directory extracted from the response message\r
 208     };\r
 209 \r
 210 \r
 211     ////////////////////////////////////////////////////////////\r
 212     /// Specialization of FTP response returning a filename lisiting\r
 213     ////////////////////////////////////////////////////////////\r
 214     class SFML_API ListingResponse : public Response\r
 215     {\r
 216     public :\r
 217 \r
 218         ////////////////////////////////////////////////////////////\r
 219         /// Default constructor\r
 220         ///\r
 221         /// \param Resp : Source response\r
 222         /// \param Data : Data containing the raw listing\r
 223         ///\r
 224         ////////////////////////////////////////////////////////////\r
 225         ListingResponse(Response Resp, const std::vector<char>& Data);\r
 226 \r
 227         ////////////////////////////////////////////////////////////\r
 228         /// Get the number of filenames in the listing\r
 229         ///\r
 230         /// \return Total number of filenames\r
 231         ///\r
 232         ////////////////////////////////////////////////////////////\r
 233         std::size_t GetCount() const;\r
 234 \r
 235         ////////////////////////////////////////////////////////////\r
 236         /// Get the Index-th filename in the directory\r
 237         ///\r
 238         /// \param Index : Index of the filename to get\r
 239         ///\r
 240         /// \return Index-th filename\r
 241         ///\r
 242         ////////////////////////////////////////////////////////////\r
 243         const std::string& GetFilename(std::size_t Index) const;\r
 244 \r
 245     private :\r
 246 \r
 247         ////////////////////////////////////////////////////////////\r
 248         // Member data\r
 249         ////////////////////////////////////////////////////////////\r
 250         std::vector<std::string> myFilenames; ///< Filenames extracted from the data\r
 251     };\r
 252 \r
 253 \r
 254     ////////////////////////////////////////////////////////////\r
 255     /// Destructor -- close the connection with the server\r
 256     ///\r
 257     ////////////////////////////////////////////////////////////\r
 258     ~Ftp();\r
 259 \r
 260     ////////////////////////////////////////////////////////////\r
 261     /// Connect to the specified FTP server\r
 262     ///\r
 263     /// \param Server :  FTP server to connect to\r
 264     /// \param Port :    Port used for connection (21 by default, standard FTP port)\r
 265     /// \param Timeout : Maximum time to wait, in seconds (0 by default, means no timeout)\r
 266     ///\r
 267     /// \return Server response to the request\r
 268     ///\r
 269     ////////////////////////////////////////////////////////////\r
 270     Response Connect(const IPAddress& Server, unsigned short Port = 21, float Timeout = 0.f);\r
 271 \r
 272     ////////////////////////////////////////////////////////////\r
 273     /// Log in using anonymous account\r
 274     ///\r
 275     /// \return Server response to the request\r
 276     ///\r
 277     ////////////////////////////////////////////////////////////\r
 278     Response Login();\r
 279 \r
 280     ////////////////////////////////////////////////////////////\r
 281     /// Log in using a username and a password\r
 282     ///\r
 283     /// \param UserName : User name\r
 284     /// \param Password : Password\r
 285     ///\r
 286     /// \return Server response to the request\r
 287     ///\r
 288     ////////////////////////////////////////////////////////////\r
 289     Response Login(const std::string& UserName, const std::string& Password);\r
 290 \r
 291     ////////////////////////////////////////////////////////////\r
 292     /// Close the connection with FTP server\r
 293     ///\r
 294     /// \return Server response to the request\r
 295     ///\r
 296     ////////////////////////////////////////////////////////////\r
 297     Response Disconnect();\r
 298 \r
 299     ////////////////////////////////////////////////////////////\r
 300     /// Send a null command just to prevent from being disconnected\r
 301     ///\r
 302     /// \return Server response to the request\r
 303     ///\r
 304     ////////////////////////////////////////////////////////////\r
 305     Response KeepAlive();\r
 306 \r
 307     ////////////////////////////////////////////////////////////\r
 308     /// Get the current working directory\r
 309     ///\r
 310     /// \return Server response to the request\r
 311     ///\r
 312     ////////////////////////////////////////////////////////////\r
 313     DirectoryResponse GetWorkingDirectory();\r
 314 \r
 315     ////////////////////////////////////////////////////////////\r
 316     /// Get the contents of the given directory\r
 317     /// (subdirectories and files)\r
 318     ///\r
 319     /// \param Directory : Directory to list ("" by default, the current one)\r
 320     ///\r
 321     /// \return Server response to the request\r
 322     ///\r
 323     ////////////////////////////////////////////////////////////\r
 324     ListingResponse GetDirectoryListing(const std::string& Directory = "");\r
 325 \r
 326     ////////////////////////////////////////////////////////////\r
 327     /// Change the current working directory\r
 328     ///\r
 329     /// \param Directory : New directory, relative to the current one\r
 330     ///\r
 331     /// \return Server response to the request\r
 332     ///\r
 333     ////////////////////////////////////////////////////////////\r
 334     Response ChangeDirectory(const std::string& Directory);\r
 335 \r
 336     ////////////////////////////////////////////////////////////\r
 337     /// Go to the parent directory of the current one\r
 338     ///\r
 339     /// \return Server response to the request\r
 340     ///\r
 341     ////////////////////////////////////////////////////////////\r
 342     Response ParentDirectory();\r
 343 \r
 344     ////////////////////////////////////////////////////////////\r
 345     /// Create a new directory\r
 346     ///\r
 347     /// \param Name : Name of the directory to create\r
 348     ///\r
 349     /// \return Server response to the request\r
 350     ///\r
 351     ////////////////////////////////////////////////////////////\r
 352     Response MakeDirectory(const std::string& Name);\r
 353 \r
 354     ////////////////////////////////////////////////////////////\r
 355     /// Remove an existing directory\r
 356     ///\r
 357     /// \param Name : Name of the directory to remove\r
 358     ///\r
 359     /// \return Server response to the request\r
 360     ///\r
 361     ////////////////////////////////////////////////////////////\r
 362     Response DeleteDirectory(const std::string& Name);\r
 363 \r
 364     ////////////////////////////////////////////////////////////\r
 365     /// Rename a file\r
 366     ///\r
 367     /// \param File :    File to rename\r
 368     /// \param NewName : New name\r
 369     ///\r
 370     /// \return Server response to the request\r
 371     ///\r
 372     ////////////////////////////////////////////////////////////\r
 373     Response RenameFile(const std::string& File, const std::string& NewName);\r
 374 \r
 375     ////////////////////////////////////////////////////////////\r
 376     /// Remove an existing file\r
 377     ///\r
 378     /// \param Name : File to remove\r
 379     ///\r
 380     /// \return Server response to the request\r
 381     ///\r
 382     ////////////////////////////////////////////////////////////\r
 383     Response DeleteFile(const std::string& Name);\r
 384 \r
 385     ////////////////////////////////////////////////////////////\r
 386     /// Download a file from the server\r
 387     ///\r
 388     /// \param DistantFile : Path of the distant file to download\r
 389     /// \param DestPath :    Where to put to file on the local computer\r
 390     /// \param Mode :        Transfer mode (binary by default)\r
 391     ///\r
 392     /// \return Server response to the request\r
 393     ///\r
 394     ////////////////////////////////////////////////////////////\r
 395     Response Download(const std::string& DistantFile, const std::string& DestPath, TransferMode Mode = Binary);\r
 396 \r
 397     ////////////////////////////////////////////////////////////\r
 398     /// Upload a file to the server\r
 399     ///\r
 400     /// \param LocalFile : Path of the local file to upload\r
 401     /// \param DestPath :  Where to put to file on the server\r
 402     /// \param Mode :      Transfer mode (binary by default)\r
 403     ///\r
 404     /// \return Server response to the request\r
 405     ///\r
 406     ////////////////////////////////////////////////////////////\r
 407     Response Upload(const std::string& LocalFile, const std::string& DestPath, TransferMode Mode = Binary);\r
 408 \r
 409 private :\r
 410 \r
 411     ////////////////////////////////////////////////////////////\r
 412     /// Send a command to the FTP server\r
 413     ///\r
 414     /// \param Command :   Command to send\r
 415     /// \param Parameter : Command parameter ("" by default)\r
 416     ///\r
 417     /// \return Server response to the request\r
 418     ///\r
 419     ////////////////////////////////////////////////////////////\r
 420     Response SendCommand(const std::string& Command, const std::string& Parameter = "");\r
 421 \r
 422     ////////////////////////////////////////////////////////////\r
 423     /// Receive a response from the server\r
 424     /// (usually after a command has been sent)\r
 425     ///\r
 426     /// \return Server response to the request\r
 427     ///\r
 428     ////////////////////////////////////////////////////////////\r
 429     Response GetResponse();\r
 430 \r
 431     ////////////////////////////////////////////////////////////\r
 432     /// Utility class for exchanging datas with the server\r
 433     /// on the data channel\r
 434     ////////////////////////////////////////////////////////////\r
 435     class DataChannel;\r
 436 \r
 437     friend class DataChannel;\r
 438 \r
 439     ////////////////////////////////////////////////////////////\r
 440     // Member data\r
 441     ////////////////////////////////////////////////////////////\r
 442     SocketTCP myCommandSocket; ///< Socket holding the control connection with the server\r
 443 };\r
 444 \r
 445 } // namespace sf\r
 446 \r
 447 \r
 448 #endif // SFML_FTP_HPP\r