HttpUpload

Detailed Description

HttpUpload is a collection of classes that makes it easy to implement a remote file manager.

HttpUpload which is internally using MultipartUpload, HttpAsynchReq, and HttpAsynchResp enables you to easily design code for uploading files using HTTP PUT and multipart POST.

The HttpResMgr in the example directory is a full file manager implementation that is internally using HttpUpload when the client requests a file upload. The following HttpDir C++ example shows how to use HttpUpload:

#include <HttpUpload.h>
#include <HttpResRdr.h>

/* MyUploadDir is a specialized HttpDir that can upload and download
   any file from a IoIntf implemenation such as a DiskIo.

   We use multiple inheritance for implementing the HttpDir and HttpUpload
   (HttpUploadCbIntf) callback interface.
*/
class MyUploadDir :
   public HttpDir, public HttpUploadCbIntf
{
      HttpUpload upload; //The upload worker class.

      //HttpUploadCbIntf callback
      static void onFile(HttpUploadCbIntf* super,
                         HttpUploadNode* node,
                         BaBool completed);

      //HttpUploadCbIntf callback
      static void onError(HttpUploadCbIntf* super,
                          HttpUploadNode* node,
                          int ecode,
                          const char* extraEcode);

      //HttpDir callback
      static int doService(HttpDir* super,
                           const char* relPath,
                           HttpCommand* cmd);

   public:
      MyUploadDir(const char* dirName, IoIntfPtr io);
};


//Called at start of multipart POST and at end of successful upload.
void
MyUploadDir::onFile(HttpUploadCbIntf* super,
                    HttpUploadNode* node,
                    BaBool completed)
{
   MyUploadDir* o = (MyUploadDir*)super; // Upcast from base
   if(completed) //A PUT or multipart POST completed.
   {
      HttpAsynchResp* resp = node->getResponse();
      //Send a simple text response message to client.
      BufPrint* out = resp->getWriter();
      if(out)  //If socket OK
         out->printf("Upload of %s completed\n", node->getName());
   }
   else //If start of a multipart file. Not used for HTTP PUT.
   {
      // This is where one can authorize the upload.
      // See the HttpResMgr class for how to deny access, if needed.
   }
}


//Called if upload failed.
void 
MyUploadDir::onError(HttpUploadCbIntf* super,
                     HttpUploadNode* node,
                     int ecode,
                     const char* extraEcode)
{
   MyUploadDir* o = (MyUploadDir*)super; /* Upcast from base */
   HttpAsynchResp* resp = node->getResponse();
   //Send a simple text response message to client.
   BufPrint* out = resp->getWriter();  
   if(out)  //If socket OK
      out->printf("Upload of %s failed\n", node->getName());
}


//The overloaded HttpDir service funtion. See HttpDir for more info.
int
MyUploadDir::doService(HttpDir* super,const char* relPath,HttpCommand* cmd)
{
   MyUploadDir* o = (MyUploadDir*)super; // Upcast from base class

   //Check that the HTTP method type is one of GET, POST, PUT, OPTION, or
   // HEAD.
   if(cmd->request.checkMethods(
         &cmd->response, HttpMethod_Get | HttpMethod_Post | HttpMethod_Put))
   {
      // Condition failed or method type is OPTION.
      // Response sent by checkMethods.
      return 0;
   }

   //If a download request.
   if(cmd->request.getMethodType() == HttpMethod_Get)
   {
      IoStat st;
      IoIntfPtr io = o->upload.getIoIntf();
      if( ! io->statFp(io,relPath, &st) && ! st.isDir )
      {  //Send to client if file found and not a directory.
         HttpResRdr::sendFile(io, relPath, &st, cmd);
         return 0; //Signal found
      }
   }
   else //Assume upload request.
   {
      if(o->upload.service(relPath, cmd))
         cmd->response.sendError(415); //Request not supported.
      return 0; //Signal found .i.e. stop searching.
   }
   return -1; //Let the virtual file system send "not found".
}


//Initiate HttpDir, HttpUploadCbIntf and HttpUpload.
MyUploadDir::MyUploadDir(const char* dirName, IoIntfPtr io) :
   HttpDir(dirName),
   HttpUploadCbIntf(onFile, onError),
   upload(io, 0, this, 5)
{
   overloadService(service); //Overload and ignore default HttpDir::service
}

Collaboration diagram for HttpUpload:

Classes
struct	HttpUploadNode
	A HttpUploadNode is dynamically created by an HttpUpload instance for each concurrent upload. More...
struct	HttpUploadCbIntf
	The HttpUploadCbIntf interface is an abstract class that must be implemented by code using the HttpUpload. More...
struct	HttpUpload
	The HttpUpload node is responsible for creating and starting HttpUploadNode instances. More...

Typedefs
typedef struct HttpUploadCbIntf	HttpUploadCbIntf
	The HttpUploadCbIntf interface is an abstract class that must be implemented by code using the HttpUpload. More...
typedef struct HttpUpload	HttpUpload
	The HttpUpload node is responsible for creating and starting HttpUploadNode instances. More...

Functions
const char *	HttpUploadNode::getName ()
	Returns the file name including the relative path.
const char *	HttpUploadNode::getUrl ()
	Returns the full URL the client used when sending data.
HttpAsynchResp *	HttpUploadNode::getResponse ()
	Fetch the response object. More...
HttpSession *	HttpUploadNode::getSession ()
	Returns the HttpSession object or null if no session object. More...
bool	HttpUploadNode::isMultipartUpload ()
	Returns true if HTTP POST. More...
	HttpUploadCbIntf::HttpUploadCbIntf (HttpUploadCbIntf_OnFile of, HttpUploadCbIntf_OnError oe)
	Initialize a HttpUploadCbIntf interface. More...
	HttpUpload::HttpUpload (IoIntfPtr io, AllocatorIntf *alloc, HttpUploadCbIntf *uploadCb, int maxUploads)
	Initialize an HttpUpload instance. More...
	HttpUpload::~HttpUpload ()
	Terminate the HttpUpload instance and all active HttpUploadNode instances.
int	HttpUpload::service (const char *name, HttpCommand *cmd, void *userdata=0)
	The HttpUpload service method. More...
IoIntfPtr	HttpUpload::getIoIntf ()
	Return a pointer to the IoIntf implementation.

Typedef Documentation

HttpUpload

typedef struct HttpUpload HttpUpload

The HttpUpload node is responsible for creating and starting HttpUploadNode instances.

The class can create N concurrent HttpUploadNodes, where N is controlled by the 'maxUploads' attribute.

HttpUploadCbIntf

typedef struct HttpUploadCbIntf HttpUploadCbIntf

The HttpUploadCbIntf interface is an abstract class that must be implemented by code using the HttpUpload.

The HttpUploadCbIntf methods are called at start of upload, end of upload, and if the upload failed.

Function Documentation

getResponse()

HttpAsynchResp * HttpUploadNode::getResponse

(

)

Fetch the response object.

Please note that calling this function terminates the current upload if not completed. The method may return NULL if the socket connection is broken.

getSession()

HttpSession * HttpUploadNode::getSession

(

)

Returns the HttpSession object or null if no session object.

The session object may expire at any time. See the explanation in the HttpSession for more information.

See also

HttpSession::incrRefCntr

HttpUpload()

HttpUpload::HttpUpload	(	IoIntfPtr	io,
		AllocatorIntf *	alloc,
		HttpUploadCbIntf *	uploadCb,
		int	maxUploads
	)

Initialize an HttpUpload instance.

Parameters

io	is a IoIntf implementation such as DiskIo.
alloc	is the allocator used when creating HttpUploadNode instances.
uploadCb	is the HttpUploadCbIntf implementation.
maxUploads	is the maximum number of concurrent uploads. The HttpUpload::service method sends a 503 HTTP response if the maximum number of concurrent uploads are reached.

HttpUploadCbIntf()

HttpUploadCbIntf::HttpUploadCbIntf	(	HttpUploadCbIntf_OnFile	of,
		HttpUploadCbIntf_OnError	oe
	)

Initialize a HttpUploadCbIntf interface.

Parameters

of	is the callback called at start or end of an upload.
oe	is the error callback method called if the upload failed.

isMultipartUpload()

bool HttpUploadNode::isMultipartUpload

(

)

Returns true if HTTP POST.

False for HTTP PUT

service()

int HttpUpload::service	(	const char *	name,
		HttpCommand *	cmd,
		void *	userdata = 0
	)

The HttpUpload service method.

This method is typically called from a HttpDir or HttpPage service method.

Parameters

name	is: if PUT: path + name relative to the I/O intf. if POST: path relative to the I/O intf. The full path+name is constructed from the name in the multipart message.
cmd	is the request/response container object.
userdata	is an optional reference that is set in the HttpUploadNode.