324 lines
9.0 KiB
C++
324 lines
9.0 KiB
C++
/**
|
|
* @file llsdrpcclient.h
|
|
* @author Phoenix
|
|
* @date 2005-11-05
|
|
* @brief Implementation and helpers for structure data RPC clients.
|
|
*
|
|
* $LicenseInfo:firstyear=2005&license=viewerlgpl$
|
|
* Second Life Viewer Source Code
|
|
* Copyright (C) 2010, Linden Research, Inc.
|
|
*
|
|
* This library is free software; you can redistribute it and/or
|
|
* modify it under the terms of the GNU Lesser General Public
|
|
* License as published by the Free Software Foundation;
|
|
* version 2.1 of the License only.
|
|
*
|
|
* This library is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
* Lesser General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with this library; if not, write to the Free Software
|
|
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
*
|
|
* Linden Research, Inc., 945 Battery Street, San Francisco, CA 94111 USA
|
|
* $/LicenseInfo$
|
|
*/
|
|
|
|
#ifndef LL_LLSDRPCCLIENT_H
|
|
#define LL_LLSDRPCCLIENT_H
|
|
|
|
/**
|
|
* This file declares classes to encapsulate a basic structured data
|
|
* remote procedure client.
|
|
*/
|
|
|
|
#include "llchainio.h"
|
|
#include "llfiltersd2xmlrpc.h"
|
|
#include "lliopipe.h"
|
|
#include "llurlrequest.h"
|
|
|
|
/**
|
|
* @class LLSDRPCClientResponse
|
|
* @brief Abstract base class to represent a response from an SD server.
|
|
*
|
|
* This is used as a base class for callbacks generated from an
|
|
* structured data remote procedure call. The
|
|
* <code>extractResponse</code> method will deal with the llsdrpc method
|
|
* call overhead, and keep track of what to call during the next call
|
|
* into <code>process</code>. If you use this as a base class, you
|
|
* need to implement <code>response</code>, <code>fault</code>, and
|
|
* <code>error</code> to do something useful. When in those methods,
|
|
* you can parse and utilize the mReturnValue member data.
|
|
*/
|
|
class LLSDRPCResponse : public LLIOPipe
|
|
{
|
|
public:
|
|
LLSDRPCResponse();
|
|
virtual ~LLSDRPCResponse();
|
|
|
|
/**
|
|
* @brief This method extracts the response out of the sd passed in
|
|
*
|
|
* Any appropriate data found in the sd passed in will be
|
|
* extracted and managed by this object - not copied or cloned. It
|
|
* will still be up to the caller to delete the pointer passed in.
|
|
* @param sd The raw structured data response from the remote server.
|
|
* @return Returns true if this was able to parse the structured data.
|
|
*/
|
|
bool extractResponse(const LLSD& sd);
|
|
|
|
protected:
|
|
/**
|
|
* @brief Method called when the response is ready.
|
|
*/
|
|
virtual bool response(LLPumpIO* pump) = 0;
|
|
|
|
/**
|
|
* @brief Method called when a fault is generated by the remote server.
|
|
*/
|
|
virtual bool fault(LLPumpIO* pump) = 0;
|
|
|
|
/**
|
|
* @brief Method called when there was an error
|
|
*/
|
|
virtual bool error(LLPumpIO* pump) = 0;
|
|
|
|
protected:
|
|
/* @name LLIOPipe virtual implementations
|
|
*/
|
|
//@{
|
|
/**
|
|
* @brief Process the data in buffer
|
|
*/
|
|
virtual EStatus process_impl(
|
|
const LLChannelDescriptors& channels,
|
|
buffer_ptr_t& buffer,
|
|
bool& eos,
|
|
LLSD& context,
|
|
LLPumpIO* pump);
|
|
//@}
|
|
|
|
protected:
|
|
LLSD mReturnValue;
|
|
bool mIsError;
|
|
bool mIsFault;
|
|
};
|
|
|
|
/**
|
|
* @class LLSDRPCClient
|
|
* @brief Client class for a structured data remote procedure call.
|
|
*
|
|
* This class helps deal with making structured data calls to a remote
|
|
* server. You can visualize the calls as:
|
|
* <code>
|
|
* response = uri.method(parameter)
|
|
* </code>
|
|
* where you pass in everything to <code>call</code> and this class
|
|
* takes care of the rest of the details.
|
|
* In typical usage, you will derive a class from this class and
|
|
* provide an API more useful for the specific application at
|
|
* hand. For example, if you were writing a service to send an instant
|
|
* message, you could create an API for it to send the messsage, and
|
|
* that class would do the work of translating it into the method and
|
|
* parameter, find the destination, and invoke <code>call</call> with
|
|
* a useful implementation of LLSDRPCResponse passed in to handle the
|
|
* response from the network.
|
|
*/
|
|
class LLSDRPCClient : public LLIOPipe
|
|
{
|
|
public:
|
|
LLSDRPCClient();
|
|
virtual ~LLSDRPCClient();
|
|
|
|
/**
|
|
* @brief Enumeration for tracking which queue to process the
|
|
* response.
|
|
*/
|
|
enum EPassBackQueue
|
|
{
|
|
EPBQ_PROCESS,
|
|
EPBQ_CALLBACK,
|
|
};
|
|
|
|
/**
|
|
* @brief Call a method on a remote LLSDRPCServer
|
|
*
|
|
* @param uri The remote object to call, eg,
|
|
* http://localhost/usher. If you are using a factory with a fixed
|
|
* url, the uri passed in will probably be ignored.
|
|
* @param method The method to call on the remote object
|
|
* @param parameter The parameter to pass into the remote
|
|
* object. It is up to the caller to delete the value passed in.
|
|
* @param response The object which gets the response.
|
|
* @param queue Specifies to call the response on the process or
|
|
* callback queue.
|
|
* @return Returns true if this object will be able to make the RPC call.
|
|
*/
|
|
bool call(
|
|
const std::string& uri,
|
|
const std::string& method,
|
|
const LLSD& parameter,
|
|
LLSDRPCResponse* response,
|
|
EPassBackQueue queue);
|
|
|
|
/**
|
|
* @brief Call a method on a remote LLSDRPCServer
|
|
*
|
|
* @param uri The remote object to call, eg,
|
|
* http://localhost/usher. If you are using a factory with a fixed
|
|
* url, the uri passed in will probably be ignored.
|
|
* @param method The method to call on the remote object
|
|
* @param parameter The seriailized parameter to pass into the
|
|
* remote object.
|
|
* @param response The object which gets the response.
|
|
* @param queue Specifies to call the response on the process or
|
|
* callback queue.
|
|
* @return Returns true if this object will be able to make the RPC call.
|
|
*/
|
|
bool call(
|
|
const std::string& uri,
|
|
const std::string& method,
|
|
const std::string& parameter,
|
|
LLSDRPCResponse* response,
|
|
EPassBackQueue queue);
|
|
|
|
protected:
|
|
/**
|
|
* @brief Enumeration for tracking client state.
|
|
*/
|
|
enum EState
|
|
{
|
|
STATE_NONE,
|
|
STATE_READY,
|
|
STATE_WAITING_FOR_RESPONSE,
|
|
STATE_DONE
|
|
};
|
|
|
|
/* @name LLIOPipe virtual implementations
|
|
*/
|
|
//@{
|
|
/**
|
|
* @brief Process the data in buffer
|
|
*/
|
|
virtual EStatus process_impl(
|
|
const LLChannelDescriptors& channels,
|
|
buffer_ptr_t& buffer,
|
|
bool& eos,
|
|
LLSD& context,
|
|
LLPumpIO* pump);
|
|
//@}
|
|
|
|
protected:
|
|
EState mState;
|
|
std::string mURI;
|
|
std::string mRequest;
|
|
EPassBackQueue mQueue;
|
|
LLIOPipe::ptr_t mResponse;
|
|
};
|
|
|
|
/**
|
|
* @class LLSDRPCClientFactory
|
|
* @brief Basic implementation for making an SD RPC client factory
|
|
*
|
|
* This class eases construction of a basic sd rpc client. Here is an
|
|
* example of it's use:
|
|
* <code>
|
|
* class LLUsefulService : public LLService { ... }
|
|
* LLService::registerCreator(
|
|
* "useful",
|
|
* LLService::creator_t(new LLSDRPCClientFactory<LLUsefulService>))
|
|
* </code>
|
|
*/
|
|
template<class Client>
|
|
class LLSDRPCClientFactory : public LLChainIOFactory
|
|
{
|
|
public:
|
|
LLSDRPCClientFactory() {}
|
|
LLSDRPCClientFactory(const std::string& fixed_url) : mURL(fixed_url) {}
|
|
virtual bool build(LLPumpIO::chain_t& chain, LLSD context) const
|
|
{
|
|
lldebugs << "LLSDRPCClientFactory::build" << llendl;
|
|
LLURLRequest* http(new LLURLRequest(LLURLRequest::HTTP_POST));
|
|
if(!http->isValid())
|
|
{
|
|
llwarns << "Creating LLURLRequest failed." << llendl ;
|
|
delete http;
|
|
return false;
|
|
}
|
|
|
|
LLIOPipe::ptr_t service(new Client);
|
|
chain.push_back(service);
|
|
LLIOPipe::ptr_t http_pipe(http);
|
|
http->addHeader("Content-Type: text/llsd");
|
|
if(mURL.empty())
|
|
{
|
|
chain.push_back(LLIOPipe::ptr_t(new LLContextURLExtractor(http)));
|
|
}
|
|
else
|
|
{
|
|
http->setURL(mURL);
|
|
}
|
|
chain.push_back(http_pipe);
|
|
chain.push_back(service);
|
|
return true;
|
|
}
|
|
protected:
|
|
std::string mURL;
|
|
};
|
|
|
|
/**
|
|
* @class LLXMLSDRPCClientFactory
|
|
* @brief Basic implementation for making an XMLRPC to SD RPC client factory
|
|
*
|
|
* This class eases construction of a basic sd rpc client which uses
|
|
* xmlrpc as a serialization grammar. Here is an example of it's use:
|
|
* <code>
|
|
* class LLUsefulService : public LLService { ... }
|
|
* LLService::registerCreator(
|
|
* "useful",
|
|
* LLService::creator_t(new LLXMLSDRPCClientFactory<LLUsefulService>))
|
|
* </code>
|
|
*/
|
|
template<class Client>
|
|
class LLXMLSDRPCClientFactory : public LLChainIOFactory
|
|
{
|
|
public:
|
|
LLXMLSDRPCClientFactory() {}
|
|
LLXMLSDRPCClientFactory(const std::string& fixed_url) : mURL(fixed_url) {}
|
|
virtual bool build(LLPumpIO::chain_t& chain, LLSD context) const
|
|
{
|
|
lldebugs << "LLXMLSDRPCClientFactory::build" << llendl;
|
|
|
|
LLURLRequest* http(new LLURLRequest(LLURLRequest::HTTP_POST));
|
|
if(!http->isValid())
|
|
{
|
|
llwarns << "Creating LLURLRequest failed." << llendl ;
|
|
delete http;
|
|
return false ;
|
|
}
|
|
LLIOPipe::ptr_t service(new Client);
|
|
chain.push_back(service);
|
|
LLIOPipe::ptr_t http_pipe(http);
|
|
http->addHeader("Content-Type: text/xml");
|
|
if(mURL.empty())
|
|
{
|
|
chain.push_back(LLIOPipe::ptr_t(new LLContextURLExtractor(http)));
|
|
}
|
|
else
|
|
{
|
|
http->setURL(mURL);
|
|
}
|
|
chain.push_back(LLIOPipe::ptr_t(new LLFilterSD2XMLRPCRequest(NULL)));
|
|
chain.push_back(http_pipe);
|
|
chain.push_back(LLIOPipe::ptr_t(new LLFilterXMLRPCResponse2LLSD));
|
|
chain.push_back(service);
|
|
return true;
|
|
}
|
|
protected:
|
|
std::string mURL;
|
|
};
|
|
|
|
#endif // LL_LLSDRPCCLIENT_H
|