Lothario
/
axmol
mirror of https://github.com/axmolengine/axmol.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #10986 from samuele3hu/v3_5_comment 

[ci skip]Update comments of some header files
This commit is contained in:
minggo 2015-03-19 20:01:43 +08:00
parent 26139a66f1 1eb1057875
commit 8075cc1602
11 changed files with 765 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
cocos/network/HttpAsynConnection.h
View File

@ -26,7 +26,7 @@
#import <Foundation/Foundation.h>
#import <Security/Security.h>
/// @cond
@interface HttpAsynConnection : NSObject <NSURLConnectionDelegate, NSURLConnectionDataDelegate>
{
}
@ -57,5 +57,5 @@
-(void) startRequest:(NSURLRequest*)request;
@end
/// @endcond
#endif //__HTTPASYNCONNECTION_H__

50
cocos/network/HttpClient.h
View File

@ -29,7 +29,6 @@
#include "network/HttpRequest.h"
#include "network/HttpResponse.h"
#include "network/HttpClient.h"
NS_CC_BEGIN
@ -41,30 +40,44 @@ namespace network {
*/
/** @brief Singleton that handles asynchrounous http requests
* Once the request completed, a callback will issued in main thread when it provided during make request
/** Singleton that handles asynchrounous http requests.
*
* Once the request completed, a callback will issued in main thread when it provided during make request.
*
* @lua NA
*/
class CC_DLL HttpClient
{
public:
/** Return the shared instance **/
/**
* Get instance of HttpClient.
*
* @return the instance of HttpClient.
*/
static HttpClient *getInstance();
/** Relase the shared instance **/
/**
* Relase the instance of HttpClient.
*/
static void destroyInstance();
/** Enable cookie support. **/
/**
* Enable cookie support.
*
* @param cookieFile the filepath of cookie file.
*/
void enableCookies(const char* cookieFile);
/**
* Set root certificate path for SSL verification.
* @param caFile a full path of root certificate.
* if it is empty, SSL verification is disabled.
*
* @param caFile a full path of root certificate.if it is empty, SSL verification is disabled.
*/
void setSSLVerification(const std::string& caFile);
/**
* Add a get request to task queue
*
* @param request a HttpRequest object, which includes url, response callback etc.
please make sure request->_requestData is clear before calling "send" here.
*/
@ -72,6 +85,7 @@ public:
/**
* Immediate send a request
*
* @param request a HttpRequest object, which includes url, response callback etc.
please make sure request->_requestData is clear before calling "sendImmediate" here.
*/
@ -79,28 +93,32 @@ public:
/**
* Change the connect timeout
* @param value The desired timeout.
* Set the timeout value for connecting.
*
* @param value the timeout value for connecting.
*/
inline void setTimeoutForConnect(int value) {_timeoutForConnect = value;};
/**
* Get connect timeout
* @return int
* Get the timeout value for connecting.
*
* @return int the timeout value for connecting.
*/
inline int getTimeoutForConnect() {return _timeoutForConnect;}
/**
* Change the download timeout
* @param value
* Set the timeout value for reading.
*
* @param value the timeout value for reading.
*/
inline void setTimeoutForRead(int value) {_timeoutForRead = value;};
/**
* Get download timeout
* @return int
* Get the timeout value for reading.
*
* @return int the timeout value for reading.
*/
inline int getTimeoutForRead() {return _timeoutForRead;};

158
cocos/network/HttpRequest.h
View File

@ -43,9 +43,11 @@ typedef void (cocos2d::Ref::*SEL_HttpResponse)(HttpClient* client, HttpResponse*
#define httpresponse_selector(_SELECTOR) (cocos2d::network::SEL_HttpResponse)(&_SELECTOR)
/**
@brief defines the object which users must packed for HttpClient::send(HttpRequest*) method.
Please refer to tests/test-cpp/Classes/ExtensionTest/NetworkTest/HttpClientTest.cpp as a sample
@since v2.0.2
* Defines the object which users must packed for HttpClient::send(HttpRequest*) method.
* Please refer to tests/test-cpp/Classes/ExtensionTest/NetworkTest/HttpClientTest.cpp as a sample
* @since v2.0.2
*
* @lua NA
*/
#if (CC_TARGET_PLATFORM == CC_PLATFORM_WP8) || (CC_TARGET_PLATFORM == CC_PLATFORM_WINRT)
@ -57,7 +59,9 @@ typedef void (cocos2d::Ref::*SEL_HttpResponse)(HttpClient* client, HttpResponse*
class CC_DLL HttpRequest : public Ref
{
public:
/** Use this enum type as param in setReqeustType(param) */
/**
* The HttpRequest type enum used in the HttpRequest::setRequestType.
*/
enum class Type
{
GET,
@ -67,11 +71,12 @@ public:
UNKNOWN,
};
/** Constructor
Because HttpRequest object will be used between UI thead and network thread,
/**
* Constructor.
* Because HttpRequest object will be used between UI thead and network thread,
requestObj->autorelease() is forbidden to avoid crashes in AutoreleasePool
new/retain/release still works, which means you need to release it manually
Please refer to HttpRequestTest.cpp to find its usage
Please refer to HttpRequestTest.cpp to find its usage.
*/
HttpRequest()
{
@ -85,7 +90,7 @@ public:
_pUserData = nullptr;
};
/** Destructor */
/** Destructor. */
virtual ~HttpRequest()
{
if (_pTarget)
@ -94,7 +99,12 @@ public:
}
};
/** Override autorelease method to avoid developers to call it */
/**
* Override autorelease method to avoid developers to call it.
* If this function was called, it would trigger assert in debug mode
*
* @return Ref* always return nullptr.
*/
Ref* autorelease(void)
{
CCASSERT(false, "HttpResponse is used between network thread and ui thread \
@ -104,38 +114,60 @@ public:
// setter/getters for properties
/** Required field for HttpRequest object before being sent.
kHttpGet & kHttpPost is currently supported
/**
* Set request type of HttpRequest object before being sent,now it support the enum value of HttpRequest::Type.
*
* @param type the request type.
*/
inline void setRequestType(Type type)
{
_requestType = type;
};
/** Get back the kHttpGet/Post/... enum value */
/**
* Get the request type of HttpRequest object.
*
* @return HttpRequest::Type.
*/
inline Type getRequestType()
{
return _requestType;
};
/** Required field for HttpRequest object before being sent.
/**
* Set the url address of HttpRequest object.
* The url value could be like these: "http://httpbin.org/ip" or "https://httpbin.org/get"
*
* @param url the string pointer.
*/
inline void setUrl(const char* url)
{
_url = url;
};
/** Get back the setted url */
/**
* Get the url address of HttpRequest object.
*
* @return const char* the pointer of _url.
*/
inline const char* getUrl()
{
return _url.c_str();
};
/** Option field. You can set your post data here
/**
* Set the request data of HttpRequest object.
*
* @param buffer the buffer of request data, it support binary data.
* @param len the size of request data.
*/
inline void setRequestData(const char* buffer, size_t len)
{
_requestData.assign(buffer, buffer + len);
};
/** Get the request data pointer back */
/**
* Get the request data pointer of HttpRequest object.
*
* @return char* the request data pointer.
*/
inline char* getRequestData()
{
if(_requestData.size() != 0)
@ -143,48 +175,78 @@ public:
return nullptr;
}
/** Get the size of request data back */
/**
* Get the size of request data
*
* @return ssize_t the size of request data
*/
inline ssize_t getRequestDataSize()
{
return _requestData.size();
}
/** Option field. You can set a string tag to identify your request, this tag can be found in HttpResponse->getHttpRequest->getTag()
/**
* Set a string tag to identify your request.
* This tag can be found in HttpResponse->getHttpRequest->getTag().
*
* @param tag the string pointer
*/
inline void setTag(const char* tag)
{
_tag = tag;
};
/** Get the string tag back to identify the request.
The best practice is to use it in your MyClass::onMyHttpRequestCompleted(sender, HttpResponse*) callback
/**
* Get the string tag to identify the request.
* The best practice is to use it in your MyClass::onMyHttpRequestCompleted(sender, HttpResponse*) callback.
*
* @return const char* the pointer of _tag
*/
inline const char* getTag()
{
return _tag.c_str();
};
/** Option field. You can attach a customed data in each request, and get it back in response callback.
But you need to new/delete the data pointer manully
/**
* Set user-customed data of HttpRequest object.
* You can attach a customed data in each request, and get it back in response callback.
* But you need to new/delete the data pointer manully.
*
* @param pUserData the string pointer
*/
inline void setUserData(void* pUserData)
{
_pUserData = pUserData;
};
/** Get the pre-setted custom data pointer back.
Don't forget to delete it. HttpClient/HttpResponse/HttpRequest will do nothing with this pointer
/**
* Get the user-customed data pointer which were pre-setted.
* Don't forget to delete it. HttpClient/HttpResponse/HttpRequest will do nothing with this pointer.
*
* @return void* the pointer of user-customed data.
*/
inline void* getUserData()
{
return _pUserData;
};
/** Required field. You should set the callback selector function at ack the http request completed
/**
* Set the target and related callback selector.
* When response come back, it would call (pTarget->*pSelector) to process something.
*
* @param pTarget the target object pointer.
* @param pSelector the callback function.
*/
CC_DEPRECATED_ATTRIBUTE inline void setResponseCallback(Ref* pTarget, SEL_CallFuncND pSelector)
{
setResponseCallback(pTarget, (SEL_HttpResponse) pSelector);
}
/**
* Set the target and related callback selector of HttpRequest object.
* When response come back, we would call (pTarget->*pSelector) to process response data.
*
* @param pTarget the target object pointer.
* @param pSelector the SEL_HttpResponse function.
*/
CC_DEPRECATED_ATTRIBUTE inline void setResponseCallback(Ref* pTarget, SEL_HttpResponse pSelector)
{
_pTarget = pTarget;
@ -195,49 +257,81 @@ public:
_pTarget->retain();
}
}
/**
* Set response callback function of HttpRequest object.
* When response come back, we would call _pCallback to process response data.
*
* @param callback the ccHttpRequestCallback function.
*/
inline void setResponseCallback(const ccHttpRequestCallback& callback)
{
_pCallback = callback;
}
/** Get the target of callback selector funtion, mainly used by HttpClient */
/**
* Get the target of callback selector funtion, mainly used by HttpClient.
*
* @return Ref* the target of callback selector funtion
*/
inline Ref* getTarget()
{
return _pTarget;
}
/* This sub class is just for migration SEL_CallFuncND to SEL_HttpResponse,
someday this way will be removed */
/**
* This sub class is just for migration SEL_CallFuncND to SEL_HttpResponse,someday this way will be removed.
*
* @lua NA
*/
class _prxy
{
public:
/** Constructor. */
_prxy( SEL_HttpResponse cb ) :_cb(cb) {}
/** Destructor. */
~_prxy(){};
/** Destructor. */
operator SEL_HttpResponse() const { return _cb; }
CC_DEPRECATED_ATTRIBUTE operator SEL_CallFuncND() const { return (SEL_CallFuncND) _cb; }
protected:
SEL_HttpResponse _cb;
};
/** Get the selector function pointer, mainly used by HttpClient */
/**
* Get _prxy object by the _pSelector.
*
* @return _prxy the _prxy object
*/
inline _prxy getSelector()
{
return _prxy(_pSelector);
}
/**
* Get ccHttpRequestCallback callback function.
*
* @return const ccHttpRequestCallback& ccHttpRequestCallback callback function.
*/
inline const ccHttpRequestCallback& getCallback()
{
return _pCallback;
}
/** Set any custom headers **/
/**
* Set custom-defined headers.
*
* @param pHeaders the string vector of custom-defined headers.
*/
inline void setHeaders(std::vector<std::string> pHeaders)
{
_headers=pHeaders;
}
/** Get custom headers **/
/**
* Get custom headers.
*
* @return std::vector<std::string> the string vector of custom-defined headers.
*/
inline std::vector<std::string> getHeaders()
{
return _headers;

90
cocos/network/HttpResponse.h
View File

@ -33,15 +33,17 @@ NS_CC_BEGIN
namespace network {
/**
@brief defines the object which users will receive at onHttpCompleted(sender, HttpResponse) callback
Please refer to samples/TestCpp/Classes/ExtensionTest/NetworkTest/HttpClientTest.cpp as a sample
@since v2.0.2
* @brief defines the object which users will receive at onHttpCompleted(sender, HttpResponse) callback.
* Please refer to samples/TestCpp/Classes/ExtensionTest/NetworkTest/HttpClientTest.cpp as a sample.
* @since v2.0.2.
* @lua NA
*/
class CC_DLL HttpResponse : public cocos2d::Ref
{
public:
/** Constructor, it's used by HttpClient internal, users don't need to create HttpResponse manually
@param request the corresponding HttpRequest which leads to this response
/**
* Constructor, it's used by HttpClient internal, users don't need to create HttpResponse manually.
* @param request the corresponding HttpRequest which leads to this response.
*/
HttpResponse(HttpRequest* request)
{
@ -57,8 +59,9 @@ public:
_responseDataString = "";
}
/** Destructor, it will be called in HttpClient internal,
users don't need to desturct HttpResponse object manully
/**
* Destructor, it will be called in HttpClient internal.
* Users don't need to desturct HttpResponse object manully.
*/
virtual ~HttpResponse()
{
@ -68,7 +71,11 @@ public:
}
}
/** Override autorelease method to prevent developers from calling it */
/**
* Override autorelease method to prevent developers from calling it.
* If this method is called , it would trigger CCASSERT.
* @return cocos2d::Ref* always return nullptr.
*/
cocos2d::Ref* autorelease(void)
{
CCASSERT(false, "HttpResponse is used between network thread and ui thread \
@ -78,44 +85,59 @@ public:
// getters, will be called by users
/** Get the corresponding HttpRequest object which leads to this response
There's no paired setter for it, coz it's already setted in class constructor
/**
* Get the corresponding HttpRequest object which leads to this response.
* There's no paired setter for it, because it's already setted in class constructor
* @return HttpRequest* the corresponding HttpRequest object which leads to this response.
*/
inline HttpRequest* getHttpRequest()
{
return _pHttpRequest;
}
/** To see if the http reqeust is returned successfully,
Althrough users can judge if (http return code = 200), we want an easier way
If this getter returns false, you can call getResponseCode and getErrorBuffer to find more details
/**
* To see if the http reqeust is returned successfully.
* Althrough users can judge if (http response code = 200), we want an easier way.
* If this getter returns false, you can call getResponseCode and getErrorBuffer to find more details.
* @return bool the flag that represent whether the http request return sucesssfully or not.
*/
inline bool isSucceed()
{
return _succeed;
};
/** Get the http response raw data */
/**
* Get the http response data.
* @return std::vector<char>* the pointer that point to the _responseData.
*/
inline std::vector<char>* getResponseData()
{
return &_responseData;
}
/** get the Rawheader **/
/**
* Get the response headers.
* @return std::vector<char>* the pointer that point to the _responseHeader.
*/
inline std::vector<char>* getResponseHeader()
{
return &_responseHeader;
}
/** Get the http response errorCode
* I know that you want to see http 200 :)
/**
* Get the http response code to judge whether response is sucessful or not.
* I know that you want to see the _responseCode is 200.
* If _responseCode is not 200, you should check the meaning for _responseCode by the net.
* @return long the value of _responseCode
*/
inline long getResponseCode()
{
return _responseCode;
}
/** Get the rror buffer which will tell you more about the reason why http request failed
/**
* Get the rror buffer which will tell you more about the reason why http request failed.
* @return const char* the pointer that point to _errorBuffer.
*/
inline const char* getErrorBuffer()
{
@ -126,9 +148,10 @@ public:
// users should avoid invoking these methods
/** Set if the http request is returned successfully,
Althrough users can judge if (http code == 200), we want a easier way
This setter is mainly used in HttpClient, users mustn't set it directly
/**
* Set whether the http request is returned successfully or not,
* This setter is mainly used in HttpClient, users mustn't set it directly
* @param value the flag represent whether the http request is successful or not.
*/
inline void setSucceed(bool value)
{
@ -136,14 +159,18 @@ public:
};
/** Set the http response raw buffer, is used by HttpClient
/**
* Set the http response data buffer, it is used by HttpClient.
* @param data the pointer point to the response data buffer.
*/
inline void setResponseData(std::vector<char>* data)
{
_responseData = *data;
}
/** Set the http response Header raw buffer, is used by HttpClient
/**
* Set the http response headers buffer, it is used by HttpClient.
* @param data the pointer point to the response headers buffer.
*/
inline void setResponseHeader(std::vector<char>* data)
{
@ -151,7 +178,9 @@ public:
}
/** Set the http response errorCode
/**
* Set the http response code.
* @param value the http response code that represent whether the request is successful or not.
*/
inline void setResponseCode(long value)
{
@ -159,7 +188,9 @@ public:
}
/** Set the error buffer which will tell you more the reason why http request failed
/**
* Set the error buffer which will tell you more the reason why http request failed.
* @param value a string pointer that point to the reason.
*/
inline void setErrorBuffer(const char* value)
{
@ -167,12 +198,21 @@ public:
_errorBuffer.assign(value);
};
/**
* Set the response data by the string pointer and the defined size.
* @param value a string pointer that point to response data buffer.
* @param n the defined size that the response data buffer would be copied.
*/
inline void setResponseDataString(const char* value, size_t n)
{
_responseDataString.clear();
_responseDataString.assign(value, n);
}
/**
* Get the string pointer that point to the response data.
* @return const char* the string pointer that point to the response data.
*/
inline const char* getResponseDataString()
{
return _responseDataString.c_str();

109
cocos/network/SocketIO.h
View File

@ -73,36 +73,88 @@ class SIOClientImpl;
class SIOClient;
/**
* @brief Singleton and wrapper class to provide static creation method as well as registry of all sockets
* Singleton and wrapper class to provide static creation method as well as registry of all sockets.
*
* @lua NA
*/
class CC_DLL SocketIO
{
public:
/**
* Get instance of SocketIO.
*
* @return SocketIO* the instance of SocketIO.
*/
static SocketIO* getInstance();
static void destroyInstance();
/**
* @brief The delegate class to process socket.io events
* The delegate class to process socket.io events.
* @lua NA
*/
class SIODelegate
{
public:
/** Destructor of SIODelegate. */
virtual ~SIODelegate() {}
/**
* Pure virtual callback function, this function should be overrided by the subclass.
*
* This function would be called when the related SIOClient object recevie messages that mean it have connected to endpoint sucessfully.
*
* @param client the connected SIOClient object.
*/
virtual void onConnect(SIOClient* client) = 0;
/**
* Pure virtual callback function, this function should be overrided by the subclass.
*
* This function would be called wwhen the related SIOClient object recevie message or json message.
*
* @param client the connected SIOClient object.
* @param data the message,it could be json message
*/
virtual void onMessage(SIOClient* client, const std::string& data) = 0;
/**
* Pure virtual callback function, this function should be overrided by the subclass.
*
* This function would be called when the related SIOClient object disconnect or recevie disconnect signal.
*
* @param client the connected SIOClient object.
*/
virtual void onClose(SIOClient* client) = 0;
/**
* Pure virtual callback function, this function should be overrided by the subclass.
*
* This function would be called wwhen the related SIOClient object recevie error signal or didn't connect the endpoint but do some network operation,eg.,send and emit,etc.
*
* @param client the connected SIOClient object.
* @param data the error message
*/
virtual void onError(SIOClient* client, const std::string& data) = 0;
/**
* Fire event to script when the related SIOClient object receive the fire event signal.
*
* @param client the connected SIOClient object.
* @param eventName the event's name.
* @param data the event's data information.
*/
virtual void fireEventToScript(SIOClient* client, const std::string& eventName, const std::string& data) { CCLOG("SIODelegate event '%s' fired with data: %s", eventName.c_str(), data.c_str()); };
};
/**
* @brief Static client creation method, similar to socketio.connect(uri) in JS
* @param delegate The delegate which want to receive events from the socket.io client
* @param uri The URI of the socket.io server
* @return An initialized SIOClient if connected successfully, otherwise NULL
* Static client creation method, similar to socketio.connect(uri) in JS.
* @param uri the URI of the socket.io server.
* @param delegate the delegate which want to receive events from the socket.io client.
* @return SIOClient* an initialized SIOClient if connected successfully, otherwise nullptr.
*/
static SIOClient* connect(const std::string& uri, SocketIO::SIODelegate& delegate);
/**
* Static client creation method, similar to socketio.connect(uri) in JS.
* @param delegate the delegate which want to receive events from the socket.io client.
* @param uri the URI of the socket.io server.
* @return SIOClient* an initialized SIOClient if connected successfully, otherwise nullptr.
*/
CC_DEPRECATED_ATTRIBUTE static SIOClient* connect(SocketIO::SIODelegate& delegate, const std::string& uri);
private:
@ -129,7 +181,9 @@ typedef std::function<void(SIOClient*, const std::string&)> SIOEvent;
typedef std::unordered_map<std::string, SIOEvent> EventRegistry;
/**
* @brief A single connection to a socket.io endpoint
* A single connection to a socket.io endpoint.
*
* @lua NA
*/
class CC_DLL SIOClient
: public cocos2d::Ref
@ -153,37 +207,64 @@ private:
friend class SIOClientImpl;
public:
/**
* Construtor of SIOClient class.
*
* @param host the string that represent the host address.
* @param port the int value represent the port number.
* @param path the string that represent endpoint.
* @param impl the SIOClientImpl object.
* @param delegate the SIODelegate object.
*/
SIOClient(const std::string& host, int port, const std::string& path, SIOClientImpl* impl, SocketIO::SIODelegate& delegate);
/**
* Destructior of SIOClient class.
*/
virtual ~SIOClient(void);
/**
* @brief Returns the delegate for the client
* Get the delegate for the client
* @return the delegate object for the client
*/
SocketIO::SIODelegate* getDelegate() { return _delegate; };
/**
* @brief Disconnect from the endpoint, onClose will be called on the delegate when complete
* Disconnect from the endpoint, onClose will be called for the delegate when complete
*/
void disconnect();
/**
* @brief Send a message to the socket.io server
* Send a message to the socket.io server.
*
* @param s message.
*/
void send(std::string s);
/**
* @brief The delegate class to process socket.io events
* Emit the eventname and the args to the endpoint that _path point to.
* @param eventname
* @param args
*/
void emit(std::string eventname, std::string args);
/**
* @brief Used to register a socket.io event callback
* Event argument should be passed using CC_CALLBACK2(&Base::function, this)
* Used to register a socket.io event callback.
* Event argument should be passed using CC_CALLBACK2(&Base::function, this).
* @param eventName.
* @param e the callback function.
*/
void on(const std::string& eventName, SIOEvent e);
/**
* Set tag of SIOClient.
* The tag is used to distinguish the various SIOClient objects.
* @param tag string object.
*/
inline void setTag(const char* tag)
{
_tag = tag;
};
/**
* Get tag of SIOClient.
* @return const char* the pointer point to the _tag.
*/
inline const char* getTag()
{
return _tag.c_str();

68
cocos/network/WebSocket.h
View File

@ -51,17 +51,21 @@ class CC_DLL WebSocket
{
public:
/**
* Construtor of WebSocket.
*
* @js ctor
*/
WebSocket();
/**
* Destructor of WebSocket.
*
* @js NA
* @lua NA
*/
virtual ~WebSocket();
/**
* @brief Data structure for message
* Data structure for message
*/
struct Data
{
@ -72,36 +76,67 @@ public:
};
/**
* @brief Errors in websocket
* ErrorCode enum used to represent the error in the websocket.
*/
enum class ErrorCode
{
TIME_OUT,
CONNECTION_FAILURE,
UNKNOWN,
TIME_OUT, /** &lt; value 0 */
CONNECTION_FAILURE, /** &lt; value 1 */
UNKNOWN, /** &lt; value 2 */
};
/**
* Websocket state
* State enum used to represent the Websocket state.
*/
enum class State
{
CONNECTING,
OPEN,
CLOSING,
CLOSED,
CONNECTING, /** &lt; value 0 */
OPEN, /** &lt; value 1 */
CLOSING, /** &lt; value 2 */
CLOSED, /** &lt; value 3 */
};
/**
* @brief The delegate class to process websocket events.
* The delegate class is used to process websocket events.
*
* The most member function are pure virtual functions,they should be implemented the in subclass.
* @lua NA
*/
class Delegate
{
public:
/** Destructor of Delegate. */
virtual ~Delegate() {}
/**
* This function to be called after the client connection complete a handshake with the remote server.
* This means that the WebSocket connection is ready to send and receive data.
*
* @param ws The WebSocket object connected
*/
virtual void onOpen(WebSocket* ws) = 0;
/**
* This function to be called when data has appeared from the server for the client connection.
*
* @param ws The WebSocket object connected.
* @param data Data object for message.
*/
virtual void onMessage(WebSocket* ws, const Data& data) = 0;
/**
* When the WebSocket object connected wants to close or the protocol won't get used at all and current _readyState is State::CLOSING,this function is to be called.
*
* @param ws The WebSocket object connected.
*/
virtual void onClose(WebSocket* ws) = 0;
/**
* This function is to be called in the following cases:
* 1. client connection is failed.
* 2. the request client connection has been unable to complete a handshake with the remote server.
* 3. the protocol won't get used at all after this callback and current _readyState is State::CONNECTING.
* 4. when a socket descriptor needs to be removed from an external polling array. in is again the struct libwebsocket_pollargs containing the fd member to be removed. If you are using the internal polling loop, you can just ignore it and current _readyState is State::CONNECTING.
*
* @param ws The WebSocket object connected.
* @param error WebSocket::ErrorCode enum,would be ErrorCode::TIME_OUT or ErrorCode::CONNECTION_FAILURE.
*/
virtual void onError(WebSocket* ws, const ErrorCode& error) = 0;
};
@ -111,7 +146,8 @@ public:
* It needs to be invoked right after websocket instance is allocated.
* @param delegate The delegate which want to receive event from websocket.
* @param url The URL of websocket server.
* @return true: Success, false: Failure
* @return true: Success, false: Failure.
* @lua NA
*/
bool init(const Delegate& delegate,
const std::string& url,
@ -119,11 +155,18 @@ public:
/**
* @brief Sends string data to websocket server.
*
* @param message string data.
* @lua sendstring
*/
void send(const std::string& message);
/**
* @brief Sends binary data to websocket server.
*
* @param binaryMsg binary string data.
* @param len the size of binary string data.
* @lua sendstring
*/
void send(const unsigned char* binaryMsg, unsigned int len);
@ -134,6 +177,7 @@ public:
/**
* @brief Gets current state of connection.
* @return State the state value coule be State::CONNECTING, State::OPEN, State::CLOSING or State::CLOSED
*/
State getReadyState();

9
cocos/scripting/lua-bindings/manual/3d/lua_cocos2dx_3d_manual.h
View File

@ -32,6 +32,15 @@ extern "C" {
}
#endif
/**
* Call this function can import the lua bindings for the cocos3d module.
* After registering, we could call the related cocos3d code conveniently in the lua.eg,.cc.Sprite3D:create(modlepath).
* If you don't want to use the cocos3d module in the lua, you only don't call this registering function.
* If you don't register the cocos3d module, the package size would become smaller .
* The current mechanism,this function is called in the lua_module_register.h
*
* @lua NA
*/
TOLUA_API int register_cocos3d_module(lua_State* L);

49
cocos/scripting/lua-bindings/manual/CCLuaBridge.h
View File

@ -36,27 +36,60 @@ extern "C" {
using namespace std;
NS_CC_BEGIN
/** LuaBridge Error enum, with inline docs. */
typedef enum {
kLuaBridgeErrorOk = 0,
kLuaBridgeErrorInvalidParameters = -1,
kLuaBridgeErrorClassNotFound = -2,
kLuaBridgeErrorMethodNotFound = -3,
kLuaBridgeErrorExceptionOccurred = -4,
kLuaBridgeErrorMethodSignature = -5,
kLuaBridgeErrorJavaVMError = -6,
kLuaBridgeErrorOk = 0, /** &lt; value 0 */
kLuaBridgeErrorInvalidParameters = -1, /** &lt; value -1 */
kLuaBridgeErrorClassNotFound = -2, /** &lt; value -2 */
kLuaBridgeErrorMethodNotFound = -3, /** &lt; value -3 */
kLuaBridgeErrorExceptionOccurred = -4, /** &lt; value -4 */
kLuaBridgeErrorMethodSignature = -5, /** &lt; value -5 */
kLuaBridgeErrorJavaVMError = -6, /** &lt; value -6 */
} LuaBridgeError;
#define LUA_BRIDGE_REGISTRY_FUNCTION "lua_bridge_function_id" // table[function] = id
#define LUA_BRIDGE_REGISTRY_RETAIN "lua_bridge_function_id_retain" // table[id] = retain count
/**
* Build bridge between ObjC and Lua.
* It makes Lua and ObjC can call each other conveniently.
* @lua NA
*/
class LuaBridge
{
public:
/**
* Get the LuaStack of LuaEngine.
* @return the LuaStack object.
*/
static LuaStack *getStack(void);
/**
* Push the function pointer corresponding to functionId on the top of lua stack by searching the `lua_bridge_function_id` table.
* If it don't find the function pointer corresponding to functionId, it will reset stack top index to the index before searching.
*
* @param functionId the value used to search the `lua_bridge_function_id` table.
*/
static int pushLuaFunctionById(int functionId);
/**
* The retain count would be increase by 1 corresponding to functionId in the `lua_bridge_function_id_retain` table if it could be found.
* If `lua_bridge_function_id_retain` table is not existed or the type of lua_bridge_function_id_retain[functionId] isn't LUA_TNUMBER, It would return 0.
* The top index of lua stack the same as before calling this function.
*
* @param functionId the value used to search the `lua_bridge_function_id_retain` table.
* @return the retain count or 0.
*/
static int retainLuaFunctionById(int functionId);
/**
*
* The retain count woulde be reduced by 1 corresponding to functionId in the `lua_bridge_function_id_retain` table if it could be found.
* If `lua_bridge_function_id` table or `lua_bridge_function_id_retain` aren't found, it would return 0.
* If the vaule of retain count is 0 after reducing, it would update the `lua_bridge_function_id_retain` table and `lua_bridge_function_id_retain` table to remove the reference corresponding to this functionId
*
* @param functionId the value used to search the `lua_bridge_function_id` table and `lua_bridge_function_id` table.
* @return the retain count or 0
*/
static int releaseLuaFunctionById(int functionId);
protected:

125
cocos/scripting/lua-bindings/manual/CCLuaEngine.h
View File

@ -38,79 +38,120 @@ extern "C" {
NS_CC_BEGIN
// Lua support for cocos2d-x
/**
* The Lua engine integrated into the cocos2d-x to process the interactive operation between lua and c++.
*
* @lua NA.
* @js NA.
*/
class LuaEngine : public ScriptEngineProtocol
{
public:
/**
* Get instance of LuaEngine.
*
* @return the instance of LuaEngine.
*/
static LuaEngine* getInstance(void);
/**
* Get defaultEngine of LuaEngine, it was deprecated.
*
* @return the instance of LuaEngine.
*/
CC_DEPRECATED_ATTRIBUTE static LuaEngine* defaultEngine(void) { return LuaEngine::getInstance(); }
/** Destrutor of LuaEngine. */
virtual ~LuaEngine(void);
/**
* Get ccScriptType of LuaEngine used, it is always kScriptTypeLua
*
* @return kScriptTypeLua.
*/
virtual ccScriptType getScriptType() override {
return kScriptTypeLua;
};
/**
* Get LuaStack of the LuaEngine.
* All the interactive operation are all base on the LuaStack.
*
* @return LuaStack object.
*/
LuaStack *getLuaStack(void) {
return _stack;
}
/**
@brief Add a path to find lua files in
@param path to be added to the Lua path
* Add a path to find lua files in
* @param path to be added to the Lua path
*/
virtual void addSearchPath(const char* path);
/**
@brief Add lua loader, now it is used on android
* Add lua loader.
* @param func a function pointer point to the loader function.
*/
virtual void addLuaLoader(lua_CFunction func);
/**
@brief reload script code contained in the given string.
@param moduleFileName String object holding the filename of the script file that is to be executed
@return 0 if the string is excuted correctly.
@return other if the string is excuted wrongly.
* Reload script code corresponding to moduleFileName.
* If value of package["loaded"][moduleFileName] is existed, it would set the vaule nil.Then,it calls executeString function.
*
* @param moduleFileName String object holding the filename of the script file that is to be executed.
* @return 0 if the string is excuted correctly or other if the string is excuted wrongly.
*/
virtual int reload(const char* moduleFileName);
/**
@brief Remove Object from lua state
@param object to remove
* Remove the related reference about the Ref object stored in the Lua table by set the value of corresponding key nil:
* The related Lua tables are toluafix_refid_ptr_mapping,toluafix_refid_type_mapping,tolua_value_root and object_Metatable["tolua_ubox"] or tolua_ubox.
* Meanwhile set the corresponding userdata nullptr and remove the all the lua function refrence corresponding to this object.
*
* In current mechanism, this function is called in the destructor of Ref object, developer don't call this functions.
*
* @param object the key object to remove script object.
*/
virtual void removeScriptObjectByObject(Ref* object) override;
/**
@brief Remove Lua function reference
* Remove Lua function reference by nHandler by setting toluafix_refid_function_mapping[nHandle] nil.
*
* @param nHandler the function refrence index to find the correspoinding Lua function pointer.
*/
virtual void removeScriptHandler(int nHandler) override;
/**
@brief Reallocate Lua function reference
* Reallocate Lua function reference index to the Lua function pointer to add refrence.
*
* @param nHandler the function refrence index to find the correspoinding Lua function pointer.
*/
virtual int reallocateScriptHandler(int nHandler) override;
/**
@brief Execute script code contained in the given string.
@param codes holding the valid script code that should be executed.
@return 0 if the string is excuted correctly.
@return other if the string is excuted wrongly.
* Execute script code contained in the given string.
*
* @param codes holding the valid script code that should be executed.
* @return 0 if the string is excuted correctly,other if the string is excuted wrongly.
*/
virtual int executeString(const char* codes) override;
/**
@brief Execute a script file.
@param filename String object holding the filename of the script file that is to be executed
* Execute a script file.
*
* @param filename String object holding the filename of the script file that is to be executed.
* @return the return values by calling executeFunction.
*/
virtual int executeScriptFile(const char* filename) override;
/**
@brief Execute a scripted global function.
@brief The function should not take any parameters and should return an integer.
@param functionName String object holding the name of the function, in the global script environment, that is to be executed.
@return The integer value returned from the script function.
* Execute a scripted global function.
* The function should not take any parameters and should return an integer.
*
* @param functionName String object holding the name of the function, in the global script environment, that is to be executed.
* @return The integer value returned from the script function.
*/
virtual int executeGlobalFunction(const char* functionName) override;
virtual int executeNodeEvent(Node* pNode, int nAction);
virtual int executeMenuItemEvent(MenuItem* pMenuItem);
virtual int executeNotificationEvent(__NotificationCenter* pNotificationCenter, const char* pszName);
@ -119,15 +160,49 @@ public:
virtual int executeLayerTouchesEvent(Layer* pLayer, int eventType, __Set *pTouches);
virtual int executeLayerTouchEvent(Layer* pLayer, int eventType, Touch *pTouch);
virtual int executeLayerKeypadEvent(Layer* pLayer, int eventType);
/** execute a accelerometer event */
virtual int executeAccelerometerEvent(Layer* pLayer, Acceleration* pAccelerationValue);
virtual int executeEvent(int nHandler, const char* pEventName, Ref* pEventSource = NULL, const char* pEventSourceClassName = NULL);
/**
* Handle the assert message.
*
* @return return true if current _callFromLua of LuaStack is not equal to 0 otherwise return false.
*/
virtual bool handleAssert(const char *msg) override;
/**
* Parse the config information data.
*
* @param type in current mechanism,it always ConfigType::COCOSTUDIO.
* @param str the information data.
* @return if __onParseConfig function exist in the Lua, it return the value that _stack->executeFunction returns otherwise return false.
*/
virtual bool parseConfig(ConfigType type, const std::string& str) override;
/**
* When some events triggered in the c++ also needs to pass on to lua to handle, we could call this function to send events.
*
* @param message the ScriptEvent object that has ScriptEventType and the pointer to information data.
* @return default return 0 otherwise return values the same as handleNodeEvent, handleMenuClickedEvent or handleCallFuncActionEvent,etc.
*/
virtual int sendEvent(ScriptEvent* message) override;
/**
* Pass on the events related with ScrollView,TableCell,AssertManager, Armature, Accelerometer, Keyboard, Touch, Touches ,Mouse and Custom event to lua to handle.
*
* @param type Different ScriptHandlerMgr::HandlerType means different processing for the data.
* @param data The pointer point to the information which should be pass on to lua, it would be parsed in the function to convert to the specific data according to the ScriptHandlerMgr::HandlerType,then pass to lua as function parameters.
* @return default return 0 otherwise return values according different ScriptHandlerMgr::HandlerType.
*/
virtual int handleEvent(ScriptHandlerMgr::HandlerType type,void* data);
/**
* Pass on the events related with TableCell and TableView to lua to handle.
*
* @param type Different ScriptHandlerMgr::HandlerType means different processing for the data.
* @param data The pointer point to the information which should be pass on to lua, it would be parsed in the function to convert to the specific data according to the ScriptHandlerMgr::HandlerType,then pass to lua as function parameters.
* @param numResults The number of the return values.
* @param func The callback would be called when numResults is > 0.
* @return default return 0 otherwise return values according different ScriptHandlerMgr::HandlerType.
*/
virtual int handleEvent(ScriptHandlerMgr::HandlerType type, void* data, int numResults, const std::function<void(lua_State*,int)>& func);
private:
LuaEngine(void)

240
cocos/scripting/lua-bindings/manual/CCLuaStack.h
View File

@ -35,105 +35,299 @@ extern "C" {
NS_CC_BEGIN
/**
* LuaStack is used to manager the operation on the lua_State,eg., push data onto the lua_State, execute the function depended on the lua_State.
* In the current mechanism, there is only one lua_State in one LuaStack object.
*
* @lua NA
* @js NA
*/
class LuaStack : public Ref
{
public:
/**
* Create a LuaStack object, it will new a lua_State.
*
*/
static LuaStack *create(void);
/**
* Create a LuaStack object with the existed lua_State
*/
static LuaStack *attach(lua_State *L);
/** Destructor. */
virtual ~LuaStack();
/**
@brief Method used to get a pointer to the lua_State that the script module is attached to.
@return A pointer to the lua_State that the script module is attached to.
* Method used to get a pointer to the lua_State that the script module is attached to.
* @return A pointer to the lua_State that the script module is attached to.
*/
lua_State* getLuaState(void) {
return _state;
}
/**
@brief Add a path to find lua files in
@param path to be added to the Lua path
* Add a path to find lua files in.
* @param path to be added to the Lua search path.
*/
virtual void addSearchPath(const char* path);
/**
@brief Add lua loader, now it is used on android
* Add lua loader.
*
* @param func a function pointer point to the loader function.
*/
virtual void addLuaLoader(lua_CFunction func);
/**
@brief reload script code contained in the given string.
@param moduleFileName String object holding the filename of the script file that is to be executed
@return 0 if the string is excuted correctly.
@return other if the string is excuted wrongly.
* Reload script code corresponding to moduleFileName.
* If value of package["loaded"][moduleFileName] is existed, it would set the vaule nil.Then,it calls executeString function.
*
* @param moduleFileName String object holding the filename of the script file that is to be executed.
* @return 0 if the string is excuted correctly or other if the string is excuted wrongly.
*/
virtual int reload(const char* moduleFileName);
/**
@brief Remove Object from lua state
@param object The object to be removed.
* Remove the related reference about the Ref object stored in the Lua table by set the value of corresponding key nil:
* The related Lua tables are toluafix_refid_ptr_mapping,toluafix_refid_type_mapping,tolua_value_root and object_Metatable["tolua_ubox"] or tolua_ubox.
* Meanwhile set the corresponding userdata nullptr and remove the all the lua function refrence corresponding to this object.
*
* In current mechanism, this function is called in the destructor of Ref object, developer don't call this functions.
*
* @param object the key object to remove script object.
*/
virtual void removeScriptObjectByObject(Ref* object);
/**
@brief Remove Lua function reference
* Remove Lua function reference by nHandler by setting toluafix_refid_function_mapping[nHandle] nil.
*
* @param nHandler the function refrence index to find the correspoinding Lua function pointer.
*/
virtual void removeScriptHandler(int nHandler);
/**
@brief Remove Lua function reference
* Reallocate Lua function reference index to the Lua function pointer to add refrence.
*
* @param nHandler the function refrence index to find the correspoinding Lua function pointer.
*/
virtual int reallocateScriptHandler(int nHandler);
/**
@brief Execute script code contained in the given string.
@param codes holding the valid script code that should be executed.
@return 0 if the string is excuted correctly.
@return other if the string is excuted wrongly.
* Execute script code contained in the given string.
*
* @param codes holding the valid script code that should be executed.
* @return 0 if the string is excuted correctly,other if the string is excuted wrongly
*/
virtual int executeString(const char* codes);
/**
@brief Execute a script file.
@param filename String object holding the filename of the script file that is to be executed
* Execute a script file.
*
* @param filename String object holding the filename of the script file that is to be executed.
* @return the return values by calling executeFunction.
*/
virtual int executeScriptFile(const char* filename);
/**
@brief Execute a scripted global function.
@brief The function should not take any parameters and should return an integer.
@param functionName String object holding the name of the function, in the global script environment, that is to be executed.
@return The integer value returned from the script function.
* Execute a scripted global function.
* The function should not take any parameters and should return an integer.
*
* @param functionName String object holding the name of the function, in the global script environment, that is to be executed.
* @return The integer value returned from the script function.
*/
virtual int executeGlobalFunction(const char* functionName);
/**
* Set the stack top index 0.
*/
virtual void clean(void);
/**
* Pushes a integer number with value intVaule onto the stack.
*
* @param intValue a integer number.
*/
virtual void pushInt(int intValue);
/**
* Pushes a float number with value floatValue onto the stack.
*
* @param floatValue a float number.
*/
virtual void pushFloat(float floatValue);
/**
* Pushes a long number with value longValue onto the stack.
*
* @param longValue a long number.
*/
virtual void pushLong(long longValue);
/**
* Pushes a bool value with boolValue onto the stack.
*
* @param boolValue a bool value.
*/
virtual void pushBoolean(bool boolValue);
/**
* Pushes the zero-terminated string pointed to by stringValue onto the stack.
*
* @param stringValue a pointer point to a zero-terminated string stringValue.
*/
virtual void pushString(const char* stringValue);
/**
* Pushes the string pointed to by stringValue with size length onto the stack.
*
* @param stringValue a pointer point to the string stringValue.
* @param length the size.
*/
virtual void pushString(const char* stringValue, int length);
/**
* Pushes a nil value onto the stack.
*/
virtual void pushNil(void);
/**
* Pushes a Ref object onto the stack.
*
* @see toluafix_pushusertype_ccobject.
*/
virtual void pushObject(Ref* objectValue, const char* typeName);
/**
* According to the type of LuaValue, it would called the other push function in the internal.
* type function
* LuaValueTypeInt pushInt
* LuaValueTypeFloat pushFloat
* LuaValueTypeBoolean pushBoolean
* LuaValueTypeString pushString
* LuaValueTypeDict pushLuaValueDict
* LuaValueTypeArray pushLuaValueArray
* LuaValueTypeObject pushObject
*
* @param value a LuaValue object.
*/
virtual void pushLuaValue(const LuaValue& value);
/**
* Pushes a lua table onto the stack.
* The key of table is the key of LuaValueDict which is std::map.
* The value of table is according to the the type of LuaValue of LuaValueDict by calling pushLuaValue,@see pushLuaValue.
*
* @param dict a LuaValueDict object
*/
virtual void pushLuaValueDict(const LuaValueDict& dict);
/**
* Pushes a lua array table onto the stack.
* The index of array table is begin at 1.
* The value of array table is according to the the type of LuaValue of LuaValueDict by calling pushLuaValue,@see pushLuaValue.
*/
virtual void pushLuaValueArray(const LuaValueArray& array);
/**
* Get the lua function pointer from toluafix_refid_function_mapping table by giving nHanlder.
* If the lua function pointer corresponding to the nHanlder isn't found, it would push nil on the top index of stack, then it would output the error log in the debug model
*
* @return true if get the no-null function pointer otherwise false.
*/
virtual bool pushFunctionByHandler(int nHandler);
/**
* Execute the lua function on the -(numArgs + 1) index on the stack by the numArgs variables passed.
*
* @param numArgs the number of variables.
* @return 0 if it happen the error or it hasn't return value, otherwise it return the value by calling the lua function.
*/
virtual int executeFunction(int numArgs);
/**
* Execute the lua function corresponding to the nHandler by the numArgs variables passed.
*
* @param nHandler the index count corresponding to the lua function.
* @param numArgs the number of variables.
* @return the return value is the same as executeFunction,please @see executeFunction
*/
virtual int executeFunctionByHandler(int nHandler, int numArgs);
/**
* Execute the lua function corresponding to the handler by the numArgs variables passed.
* By calling this function, the number of return value is numResults(may be > 1).
* All the return values are stored in the resultArray.
*
* @param nHandler the index count corresponding to the lua function.
* @param numArgs the number of variables.
* @param numResults the number of return value.
* @param resultArray a array used to store the return value.
* @return 0 if it happen error or it hasn't return value, otherwise return 1.
*/
virtual int executeFunctionReturnArray(int handler,int numArgs,int numResults,__Array& resultArray);
/**
* Execute the lua function corresponding to the handler by the numArgs variables passed.
* By calling this function, the number of return value is numResults(may be > 1).
* All the return values are used in the callback func.
*
* @param handler the index count corresponding to the lua function.
* @param numArgs the number of variables.
* @param numResults the number of return value.
* @param func callback function which is called if the numResults > 0.
* @return 0 if it happen error or it hasn't return value, otherwise return 1.
*/
virtual int executeFunction(int handler, int numArgs, int numResults, const std::function<void(lua_State*,int)>& func);
/**
* Handle the assert message.
*
* @return return true if current _callFromLua of LuaStack is not equal to 0 otherwise return false.
*/
virtual bool handleAssert(const char *msg);
/**
* Set the key and sign for xxtea encryption algorithm.
*
* @param key a string pointer
* @param keyLen the length of key
* @param sign a string sign
* @param signLen the length of sign
*/
virtual void setXXTEAKeyAndSign(const char *key, int keyLen, const char *sign, int signLen);
/**
* free the key and sign for xxtea encryption algorithm.
*/
virtual void cleanupXXTEAKeyAndSign();
/**
* Loads a buffer as a Lua chunk.This function uses lua_load to load the Lua chunk in the buffer pointed to by chunk with size chunkSize.
* If it supports xxtea encryption algorithm, the chunk and the chunkSize would be processed by calling xxtea_decrypt to the real buffer and buffer size.
*
* @param L the current lua_State.
* @param chunk the buffer pointer.
* @param chunSize the size of buffer.
* @param chunkName the name of chunk pointer.
* @return 0, LUA_ERRSYNTAX or LUA_ERRMEM:.
*/
int luaLoadBuffer(lua_State *L, const char *chunk, int chunkSize, const char *chunkName);
/**
* Load the Lua chunks from the zip file
*
* @param zipFilePath file path to zip file.
* @return 1 if load sucessfully otherwise 0.
*/
int loadChunksFromZIP(const char *zipFilePath);
/**
* Load the Lua chunks from current lua_State.
*
* @param l the current lua_State.
* @return 1 if load sucessfully otherwise 0.
*/
int luaLoadChunksFromZIP(lua_State *L);
protected:

10
cocos/scripting/lua-bindings/manual/audioengine/lua_cocos2dx_audioengine_manual.h
View File

@ -32,6 +32,16 @@ extern "C" {
}
#endif
/**
* Call this function can import the lua bindings for the audioengine module.
* After registering, we could call the related audioengine code conveniently in the lua.eg,.ccexp.AudioEngine:stop(audioID).
* If you don't want to use the audioengine module in the lua, you only don't call this registering function.
* If you don't register the audioengine module, the package size would become smaller .
* The current mechanism,this function is called in the lua_module_register.h
*
* @lua NA
*/
TOLUA_API int register_audioengine_module(lua_State* L);