1 Connection manager ,  useful classes for API and  result acceptance handlers/callbacks

2 Peer session creation

3 Peer lookup queries

4 Peer state tracing / changes notifications

5 Instant messages

6 NAT Traversal - Direct communication tunnel creation between peers

7 Using virtual index storage

8 Security, key exchange and data encryption/decryption

9 Add firewall exception  for your application in application installer

 

To use quickP2P c++ stl api with your  project you first need to include:

- linux / Android : libquickP2PLib.so

- Mac OS / IOS: libquickP2PLib.a

- Windows: quickP2PLib.dll

into your project.  As for CPU architecture x86/x64/arm6/arm7/arm8/arm9/mips you need to make sure you have right build.

Also you need to include <qp2p.h> located in header files shipped with lib into source files using qp2p library directly. 

If you want to use qp2p API on some little known platform it's not problem to obtain correct build from us (such request before making contract with us is not possible) if we can have access to right build tool.  If platform has support for BSD sockets and POSIX standard we should be able to make build without much of problems. 

 1 Connection manager ,  useful classes for API and  result acceptance handlers/callbacks

 

ConnectionManager  is main object you use with API.  All client operations are initiated using methods in this class with exception of virtual index manager which is sub object of ConnectionManager(ConnnectionManager.VNIndexManager()).

 

quickP2P API is based on asynchronous model. You initiate operation by making request and you wait for result  in event handler or provided callback. For most of the requests there is option to choose between event handler and callback to handle response depending what you want to do or what you prefer.

This would be the comparison of using events and callbacks.

 

Since we wanted that all our API versions look and function as much same as they can be we invented special delegate/event system that is similar as in .NET with easy way of controlling object lifetime.

Since asynchronous  API heavily depends on  delegate/events we will describe in details use of this features although they are not directly related to main API functionalities.  You need to understand this specific concepts first to be able to efficiently use API.

1.1 Event.h - quickP2P  lib delegate/event system

 

quickP2Plib c++ STL lib has its own lightweight delegate/event implementation.  Entire code for this subsystem is placed in single file - Event.h.  QuickP2P events/delegates concept is almost same as in .NET.

This template classes are important for use:

- qp2plib::DelegateStatic - points to static class functions or global functions

- qp2plib::DelegateMember - points to class or struct member functions

- qp2plib::DelegateStatic_objc - points to static class functions or global functions defined in Objective C

- qp2plib::DelegateMember_objc - points to class or struct member functions defined in Objective C

- qp2plib::Event - can be described as list you can add/remove delegates to. On rising all contained delegates are executed with given arguments

Each delegate/event can be specified to have 0-8 arguments for handler function. Delegates you add to some Event must have matching handler argument types.

Next we will show use of each of them, best from example program:

#include <qp2p.h>

void IamGlobalFunction(char* text,int number){

       printf("\nfrom global function text: %s , number: %d",text,number);

}

 

class SomeClass{

public:

       static void IamStaticFunction(char* text,int number){

              printf("\nfrom static class function text: %s , number: %d",text,number);

       }

 

       void IamMemberFunction(char* text,int number){

           printf("\nfrom class member function text: %s , number: %d",text,number);

       }

};

 

int main(int argc, char* argv[])

{

       //we create delegate objects , we set constructor argument deleteAutomaticaly = true so we dont need to delete manually

       qp2plib::Delegate<char*,int>* twoParmDelegate1

              = new qp2plib::DelegateStatic<char*,int>(IamGlobalFunction,true);

       qp2plib::Delegate<char*,int>* twoParmDelegate2

              = new qp2plib::DelegateStatic<char*,int>(&SomeClass::IamStaticFunction,true);

      

       SomeClass *temp = new SomeClass();

       //note firts template argument is name of class, also we set deleteAutomaticaly = true and deleteMemberObject = true

       //so we dont need to delete after temp and twoParmDelegate3 becuse they will be deleted after execution

       qp2plib::Delegate<char*,int>* twoParmDelegate3

              = new qp2plib::DelegateMember<SomeClass,char*,int>(temp,&SomeClass::IamMemberFunction,true,true);

       //If you want invoking and executing code in same code block:

       struct my_functor{

              void doCallback(char* text,int number){

                  printf("\nfrom functor text: %s , number: %d",text,number);

              }

       };

       my_functor *temp2 = new my_functor();

       qp2plib::Delegate<char*,int>* twoParmDelegate4

              = new qp2plib::DelegateMember<my_functor,char*,int>(temp2,&my_functor::doCallback,true);

       //we invoke our delegates

       (*twoParmDelegate1)("some text for global fn",1);

       (*twoParmDelegate2)("some text for static fn",2);

       (*twoParmDelegate3)("some text for class member fn",3);

       (*twoParmDelegate4)("some text for functor member fn",4);

 

       return 0;

}

In above example we demonstrated use of qp2p delegates to invoke global function, static class member function , class member function and functor  that gave us ability to place invoking and executing code in same code block.

Next see modified example where we invoke all  4 of them at once  with event:

 #include <qp2p.h>

void IamGlobalFunction(char* text,int number){

       printf("\nfrom global function text: %s , number: %d",text,number);

}

 

class SomeClass{

public:

       static void IamStaticFunction(char* text,int number){

              printf("\nfrom static class function text: %s , number: %d",text,number);

       }

 

       void IamMemberFunction(char* text,int number){

           printf("\nfrom class member function text: %s , number: %d",text,number);

       }

};

 

int main(int argc, char* argv[])

{

      

       qp2plib::Event<char*,int> myEvent;

 

       myEvent += new qp2plib::DelegateStatic<char*,int>(IamGlobalFunction,true);

       myEvent += new p2plib::DelegateStatic<char*,int>(&SomeClass::IamStaticFunction,true);

      

       SomeClass *temp = new SomeClass();

       myEvent += new qp2plib::DelegateMember<SomeClass,char*,int>(temp,&SomeClass::IamMemberFunction,true,true);

 

       struct my_functor{

              void doCallback(char* text,int number){

                  printf("\nfrom functor text: %s , number: %d",text,number);

              }

       };

       my_functor *temp2 = new my_functor();

       myEvent += new qp2plib::DelegateMember<my_functor,char*,int>(temp2,&my_functor::doCallback,true);

 

       //now we will invoke

       myEvent("Event invoked me",1000);

 

       return 0;

}

 

Event must have same template argument signature as delegates you put in it. += and -= are operators designed so event object would look similar as in C#. deleteAutomaticaly argument in delegate constructor would get other meaning if delegate is put into event. Instead of deleting after execution deleteAutomaticaly will be used by event object to mark delegate deletion when itself is in disposal state. Note taht in this examples we talked about cases when we use dynamic HEAP allocation. If you mark deleteAutomaticaly on delegate that is constructed statically delete would be applied and that would cause memory access fault. 

If you looked this examples with care you got an point  of qp2p event/delegates use if you used .NET events you notice they function very similarly except this are native c++ cross-platform events/delegates . You note there are no delete statement at end of program and we did not miss that because this is scrap example. We controlled HEAP disposal by providing deleteAutomatically and deleteMembersObject arguments to true.  You can copy/past  above codes to your project sources if you wish to practice.

qp2plib::DelegateStatic_objc  and  qp2plib::DelegateMember_objc basicly accept Objective C selectors to point to objective c  methods and id type in case of  qp2plib::DelegateMember_objc to point to object having method to execute. This makes qp2p c++ api fully mixable with objective c:

 _ConnectionManager->onStatusChange += new qp2plib::DelegateMember_objc<qp2plib::ConnectionManager *, qp2plib::ConnectionManager::ConnectionManagerStatus>(self,@selector(onStatusChange::),true);

......

-(void) onStatusChange: (qp2plib::ConnectionManager*) sender : (qp2plib::ConnectionManager::ConnectionManagerStatus) newStatus{

    .........

}

Note @selector(onStatusChange::) has two ':' at end after method name which corresponds to number of arguments.

1.2 Other useful utilities of qP2P c++ Api

 

Making your own cross-platform code entities can sometimes be harsh and having ready solutions can really push thing forward.  Since we had to make few such things for API itself we also exposed them so you could use them. Here we will mention few we think could really help you  with other parts of your project.

- qp2plib::IP4Address

Represents IP4 address object in machine byte order. It has handy ToString() and can be easily converted to sockaddr_in. Also you can do IP4Address myAddress = "88.20.0.20"; or IP4Address myAddress = "somedomain.com"; 

-qp2plib::IPEndPoint

 Represent IP4Address:port pair. It's implicitly castable to  sockaddr_in and vice versa. It has handy ToString() ,ToByteArray and FromByteArray methods. sockadr  is different on almost all platforms and using IPEndPoint enables you to easily overcome this.  You can cast it anytime to sockadr_in when you need to pass it to socket functions. It has built in DNS resolve so IPEndPoint ep = "somedomin.com:80" or IPEndPoint ep = "88.20.0.22:80"  are valid.

-qp2plib::Guid    

.NET like guid (compatibile). Represents 16 byte object you use as unique identificator.  You can extract random values by taking last bytes form this object .

-qp2plib::DnsHelper::GetHostName - gets host name of local host

-qp2plib::DnsHelper::GetFirstHostAddress - gets first IP4 address of  some host, there is also function to get all addresses of some dns name

-qp2plib::UTIL::GetCurrentTimeMilisec - gets current time in milliseconds, it's not accurate in terms of current day time but it's good for synchronization 

-qp2plib::UTIL::DownloadURL - can be used do download pages/files usingHTTP/HTTPS  protocol

-qp2plib::UTIL::GetOS - gets current operating system name

-qp2plib::NetworkHelper::getBindAddressForRemoteAddress - when machine/device has multiple network interfaces this is best cross-platform utility to check which local adder will socket take to connect to some remote address

qp2plib:UInt64 and qp2plib:Int64  are useful because incompatibilities of long and unsigned long type between platforms.

 

1.3 Event s in quickP2P API

 

 

- When you hook event once it will execute response every time correspondent request arrives until you unhook it.

 

- If you have both event hooked and callback provided to execute on request completion first event is triggered then callback

 

- Arguments values are guaranteed inside  handler functions bodies. After execution(s) argument values are disposed so be sure if you use this values to set other variables to do it by copying values NOT BY REF!

One caracteristical example would be handler that executes on instant message reception:

 

void onReceiveInstantMessage(qp2plib::Guid *FromPeerUID,qp2plib::Guid *FromPeerCheckpointUID,qp2plib::Guid *IMessageUID,int MessageType,unsigned char* data,int len){

....

 

Note argument data of type unsigned char*. If you plan to store bytes from that argument to some variable for later use make sure you do it by copying bytes with memcpy or whatever you use.

 

- quickP2P will execute event handlers and callbacks on one of its 3 running threads. You must be careful not to do long running tasks inside event or callback handler body because you may block API execution. Instead make sure all your long running task you starts from event of callback body are transferred to other threads. Note this behavior is specific for c++ API, C# and Java wrapped API have other rules. 

To demonstrate that, we will turn again to demo project provided with application to see how is this solved. See qp2p_SimplestDemo_FileTransfer.cpp

 

In some moment we initiate tunnel creation to other peer:

....

//STEP5 we found peer so now we will do NAT travaresal operation to open direct communication tunnel to it

//here we initioate NAT Traversal tunnel opening operation

//on completeion onPeerConnectEventHandler of onPeerConnectFailureEventHandler will trigger

qp2plib::Guid connectTUID = CM->Connect(Peers[0],qp2plib::CT_TCP);

//NEXT we wait for result in onPeerConnectEventHandler, on other side onPeerAcceptEventHandler will trigger

....

 

When operation finishes with success , this handler will be triggered:

 

....

void onPeerConnectEventHandler(qp2plib::Peer *remotePeer,qp2plib::Guid * transactionUID){

       //STEP6 - 1 - we have tunnel we will now do file transfer - send

      

       std::map<std::string,std::string>::iterator it = sendFileTasks.find(transactionUID->ToString());

       if(it == sendFileTasks.end()) {

              printf("\nUnrecognised peer connect tranasaction UID: %. Transaction will be terminated!\n",transactionUID->ToString().c_str());

              qp2plib::Uninetwork::SocketClose(remotePeer->TunnelSocket);

       }else{

              //file transfer could be long running operation that could block api if we do it all in event hendler body.

              //So we create new thread and pass it all information needed for file transfer.

              FileTransferInfo *ftr = new FileTransferInfo();

              ftr->File = (*it).second;//this is send

              ftr->isSend = true;

              ftr->P = *remotePeer;//remotePeer->TunnelSocket is traversaled connected socket - note this is just regular socket regardless of alias type qp2plib::Socket

             

              printf("\nSending file: %s [0%%]\n>>",ftr->File.c_str());

 

              //When we get connected/ready socket it's our responisibility from then on.

              //In case we end application while file transfer active socked handle may stay

              //unclosed. So we store our sockets in some list for taht case if we need to

              //close them before they finish their job.

              kill_me.push_back(remotePeer->TunnelSocket);

 

              //we create thread and pass it all needed information for file transfer

              tthread::thread *send_thr = new tthread::thread(FileTransferWorker,ftr);

             

              //we no longer need to keep track of transaction

              sendFileTasks.erase(it);

 

             

       }

}

 

 

....

 

So you see we have created new thread to run file transfer in method FileTransferWorkeronPeerConnectEventHandler method is executed from internal API thread. If we would just do file send loop in that method body we would block that API thread until file transfer completes. That's why we  created new thread to execute file transfer leaving API internal thread to do its job.

1.4 Callbacks

 

Callbacks are usually provided as optional arguments to request invoking methods  and are executed on request completion only once .

Callback are executed from "some" of 3 internal threads that accepted request response, so watch for that not to block them using long running operations inside of their body. Make sure you  transfer long running tasks to other thread.

 

You would use callback when you don't want to hook event to execute every time you receive response to some common action. Callbacks are sometimes particularly handy in combination with functor. You can see from demo application provided with this document way we used functor for session open callback that enabled us to define request and response process code in same method body.  Also functor is basically structure that can have other members  so you can define additional variables to store some info usually needed to relate particular request with correspondent response. We will describe that referring to way we did CM->connect (NAT Traversal) operation.  It is possible to issue multiple connect request in short time period. All of them would result in onPeerConnectEventHandler triggering. In demo we used additional data structure std::map<std::string,std::string> sendFileTasks; so we could know which event triggering is for which file to send by transaction UID. Using  transaction UID is way to do that using events , and also we could use same approach in case we use just callback. Here we will describe how same thing could be done using callback in functor that contains additional info data.

 

struct onPeerConnectCallbackFunctor{

       std::string FileToSend;

       onPeerConnectCallbackFunctor(std::string file){

                              FileToSend = file;

       }

 

       void doCallback(qp2plib::Peer *remotePeer, qp2plib::Guid *PeerCheckpointUID, qp2plib::Guid *PeerUID, qp2plib::Guid *transactionUID, bool success, qp2plib::ConnectionManager::PeerConnectFailureReason reason){

              if(success){

                     FileTransferInfo *ftr = new FileTransferInfo();

//we have availabe FileToSend variable from functor memeber

                     ftr->File = this->FileToSend;                  

                     ftr->isSend = true;

//remotePeer->TunnelSocket is traversaled connected socket - note this is just regular socket regardless of alias type qp2plib::Socket

                     ftr->P = *remotePeer;

                     printf("\nSending file: %s [0%%]\n>>",ftr->File.c_str());

                     kill_me.push_back(remotePeer->TunnelSocket);

//we create thread and pass it all needed information for file transfer

                     tthread::thread *send_thr = new tthread::thread(FileTransferWorker,ftr);

              }else

                     printf("\nNAT Travesal operation with transaction UID: %s intended for creation of tunnel for send transfer of [%s] failed because of: %s\n\n>>", transactionUID->ToString().c_str(),this->FileToSend.c_str(), qp2plib::ConnectionManager::PeerConnectFailureReasonName(reason).c_str());

              }

       };

 

onPeerConnectCallbackFunctor *pccf = new onPeerConnectCallbackFunctor((*it).second);

CM->Connect(

              Peers[0],

              qp2plib::CT_TCP,

              qp2plib::IPEndPoint::ANY(),

              new qp2plib::DelegateMember<onPeerConnectCallbackFunctor,qp2plib::Peer*, qp2plib::Guid*, qp2plib::Guid*, qp2plib::Guid*, bool, qp2plib::ConnectionManager::PeerConnectFailureReason>(pccf,&onPeerConnectCallbackFunctor::doCallback,true,true));

 

 

So we added FileToSend variable to our functor struct and we use it to pass file path to callback executing handler. Here we did not need std::map<std::string,std::string> sendFileTasks; struct.

 

There are situations where  you might find using both callback and event handle useful.  For example session opening. If CM->MaintainSession is set to true (default) , on session loss connection manager will wait until session creation is possible again (internet connection temporal loss for example) and initiate session open again in background. On success it will trigger event

ConnectionManager::onSessionOpenSuccess if we did not use this event just callback we will never know that happened. Also me might want to execute different handler for first time session open and later session recoveries. So this might be practice:

- For first time session open use callback

- In callback handler body then  hook event ConnectionManager::onSessionOpenSuccess

- On ConnectionManager::onSessionOpenSuccess triggering you can execute code for case of session recovery

 

Ok, we could use event and some bool variable for that but point was to describe to you one more concept.

 

 

 

 

 2 Peer session creation

 

For quickP2P client , to be able to do any operation like tunnel opening, sending instant message, searching peers ...  we first need to join abstract peer-to-peer network  like you connect to internet when your computer powers up . Steps for joining application peer to super-node network would be this:

1 - Create ConnectionManager object to handle operations,  set required C.M. properties , handles  ... 

                It's always required to set access tokens :

CM->setAccessTokens("00000000-XXXX-XXXX-XXXX-XXXXXXXXXXXX","00000000-XXXX-XXXX-XXXX-XXXXXXXXXXXX","");

 

First argument is provider UID , second application UID , third is access key. You can see this values in you provider portal.

 

2 - Set some meta-data so other peers can find us and we can find them by filtering values

CM->LocalPeer["some_meta"] = "bla bla bla";

CM->LocalPeer["email"] = "This email address is being protected from spambots. You need JavaScript enabled to view it.";

CM->LocalPeer["gender"] = "male";

 

you can also alter these properties later after session open , you need to call

CM->BrodcastStateChange() to update local peer information on network.

 

 

3-Initate ConnectionManager::Open to open session

 

4- Wait open session completion handler to execute

(note ,after session open completion avoid initiating connect -  "tunnel open" operation in next 2-3 sec to give time to api to inspect your network environment properly )

Once we have established session with super-node we can:

- Query for other peers on network (Peer lookup) with mongo db-like queries in our application scope

- Register for peers’ status tracking and receive notifications about changes

- Send/Receive instant messages

- Open communication tunnels to other peers and other peers can open tunnels to us

- Use virtual index manager  if we need it:

                - Create|Delete|Edit Virtual Networks|Users

                - Search virtual networks|users with mongo db like queries

                - Join|Un-join users to networks

                ....

We will talk about all of these operations in following texts

 

 3 Peer lookup queries      

 

Peer lookup queries query for peers that are currently online. Query request is initiated using

qp2plib::Guid QueryTransactionID  = CM->Query(::std::string QueryText , qp2plib::ConnectionManager::PeerQueryCompleted Callback = NULL, int page = 0, int pageLimit = 64);

 

or handy overload if we need to check single peer:

qp2plib::Guid QueryTransactionID  = CM->Query(qp2plib::Guid PeerUID, qp2plib::ConnectionManager::PeerQueryCompleted Callback = NULL)

 

methods of ConnectionManager object.  Callback and event handler method has in-print like this:

typedef Delegate<Peer*,intbool, Guid*, intintint>* PeerQueryCompleted;

 

Agruments:

FoundPeers List of peers returned by query

Count Number of peers returned by query

Completed If completed then true, not that somitimes result will contain peers but this value will be false. This can happen for example if 10000000 peers are found by serch creterium , and operation timeout expires before all results are collected

QueryTransactionID Transaction ID of query request

Page Page returned if pagination exists

PageLimit Number of peers per page if pagination exists

TotalPeers Total number of peers matched by query

 

Event hook example:

 CM->onPeerQueryResponse += new qp2plib::DelegateStatic<qp2plib::Peer*,int,bool,qp2plib::Guid*,int,int,int>(onPeerQueryCompleted,true);

 

Query text format is mongo db like query with the exception that you don't put opening and closing brackets.

Let's say we defined some meta properties for our peer like this:

            CM->LocalPeer["City"] = "Palo Alto";

            CM->LocalPeer["Sex"] = "female";

            CM->LocalPeer["Email"] = "This email address is being protected from spambots. You need JavaScript enabled to view it.";

            CM->LocalPeer["Age"] = "31";

 

Here are some examples of queries that will include this peer in result:

Find peer with email "This email address is being protected from spambots. You need JavaScript enabled to view it." that is currently online :

CM->Query((std::string)"\"Properties.Email\":\"This email address is being protected from spambots. You need JavaScript enabled to view it.\"") ;

Find peers with email contained in this list [This email address is being protected from spambots. You need JavaScript enabled to view it., This email address is being protected from spambots. You need JavaScript enabled to view it., This email address is being protected from spambots. You need JavaScript enabled to view it.] that are currently online:

CM->Query((std::string)"\"Properties.Email\": {$in:[\"This email address is being protected from spambots. You need JavaScript enabled to view it.\",\"This email address is being protected from spambots. You need JavaScript enabled to view it. \",\"This email address is being protected from spambots. You need JavaScript enabled to view it.\"]}") ;

Find female peers form Palo Alto that are currently online:

CM->Query((std::string)"\"Properties.City \":\"Palo Alto\", \"Properties.Sex\":\"female\"") ;

Find female peers form Palo Alto with above 30 that are currently online:

CM->Query((std::string)"\"Properties.City \":\"Palo Alto\", \"Properties.Sex\":\"female\", \"Properties.Age\":{$gt:30}") ;

You can test your queries on provider portal.

 

 4 Peer state tracing / changes notifications

 

There is often a need for some peer to have some state on network, like away, busy, available .... You probably seen that as common feature of chat applications. If you think you could achieve same functionality using Instant messages or something else you are right but this provides you more elegant way of transferring such information to peers instantly. Also there are certain situations when this comes handy as irreplaceable feature. Imagine you have some chat like application and you keep your peer buddies in some list or dictionary... your buddy kid  rips power cables from his computer so his application don't manage to notify you that he is offline. Super-node will notice that in max 90sec, and if you registered for that peer state tracking you will get notification that he is offline.

To use this feature you need to hook event to accept notifications:

CM->onPeerStateChanged += new qp2plib::DelegateStatic<qp2plib::Peer*,qp2plib::UInt32>(onPeerStateChanged,true);

.....

void onPeerStateChanged(qp2plib::Peer *P,qp2plib::UInt32 newPeerState){

       if(newPeerState == 0){//0 - is reserved for disconnected state, 1 - initial connected state, all values > 1 are available for free use

              Peers_List.erase(P->UID);//Peer got disconnected we remove it from our internal list

       }

}

 

This is rare case where you don't have option to use callback because you never know when notification will come.

Also you have to inform super-nodes that you want to be notified about that peer changes. You do that using :

CM->RegisterStateTracking

 

method having 4 overloads.  Common place to place RegisterStateTracking method is in a body of peer query response handler because that is moment when you get fresh information of who is online.  If peer goes offline you will get qp2plib::Peer::DisconnectedState  (=0) state argument value. If he comes back he needs to inform you that he is back online and you again need to register for its state tracking again.  So status track is valid until peer goes offline, if he comes back you need to register state tracking again. Also you see there is a need to combine instant messages with this to make it fully usable , why:

- You do peer query and you get fresh information about online peers , but after 30 sec some peer that should be  visible to you by application terms appears on network. You don't know that he is online in that moment and you would not know that he is online until you do peer query again, but he also does peer query and he knows you are online so all he has to do is to inform you about that. He can do that by simply sending you some instant message.

CM->SendInstantMessage

 (YourPeer,"some text - not nessery",YourApplicationMessagesEnum::IM_ONLINE);

 

void onReceiveInstantMessage(qp2plib::Guid *FromPeerUID,qp2plib::Guid *FromPeerCheckpointUID,qp2plib::Guid *IMessageUID,int MessageType,unsigned char* data,int len){

{

       if(MessageType == (int)YourApplicationMessagesEnum::IM_ONLINE){

              //update your list or do query to check all again

       }else....

}

 

We will talk about instant messages later so you could fully understand this code.

In state changed notification handler: void onPeerStateChanged(qp2plib::Peer *P,qp2plib::UInt32 newPeerState){

you see two arguments Peer and State. First is complete fresh peer object of peer whose state changed and State is new state of that peer.  You notice it is unsigned int value so you are free to use any value in range from 2 to uint.MAX for your application.

Values 0 and 1 are reserved for

qp2plib:Peer::DisconnectedState    = 0;

qp2plib:Peer::AuthentificatedState = 1;

 

System depends on them so you cannot use these values for anything else.

To notify other peers about your state change code would be something like this:

- for example you are now  busy

CM->LocalPeer.State = (uint)MyApplicationPeerStateEnums.BUSY;

CM->BrodcastStateChange();

 

So we use CM->BrodcastStateChange(); to inform others of our state changes. This function also updates our peer object information on super-node so we also use it when we change meta properties while session is active.

You don't need  to do state broadcast when you are closing session/disposing C.M. because ConnectionManager  will do that automatically.

 

 5 Instant messages

 

Instant messages are carried using super-nodes, and their purpose is to transfer short messages between peers in network.  Often it is not practical to always open direct communication channel between two peers if one needs to inform other about something  because tunnel creation takes 1-15s and also maybe we want first other peer to confirm that he willingly accepts that connection . These are commonly some control messages from your application or something like chat messages.

To be able to receive them you need to hook following event handler:

CM->onReceiveInstantMessage

+= new qp2plib::DelegateStatic<qp2plib::Guid*,qp2plib::Guid*,qp2plib::Guid*,int,unsigned char*,int>(onReceiveInstantMessage,true);

 

.....

 

void onReceiveInstantMessage(qp2plib::Guid *FromPeerUID,qp2plib::Guid *FromPeerCheckpointUID,qp2plib::Guid *IMessageUID,int MessageType,unsigned char* data,int len){

 

    if (MessageType == (int)YourApplicationMessagesEnum::TextMessage) {

             //do something

    }

    else if (MessageType == (int)YourApplicationMessagesEnum::IM_ONLINE) {

             //do something

    }

    else if (MessageType == (int)YourApplicationMessagesEnum::ALLOW_FILE_TRANSFER){

             //do something

    }...

}

 

To send instant message you use one of 4 overloads of cm.SendInstantMessage function:

 

Guid SendInstantMessage(Guid RemotePeerCheckpointUID, Guid RemotePeerUID, unsigned char* message_buffer, int message_len, int InstantMessageType = 0, SendInstantMessageComplete Callback = NULL);

 

Guid SendInstantMessage(Guid RemotePeerCheckpointUID, Guid RemotePeerUID, ::std::string Message, int InstantMessageType = 0, SendInstantMessageComplete Callback = NULL);

 

Guid SendInstantMessage(Peer &Peer, unsigned char* message_buffer, int message_len, int InstantMessageType = 0, SendInstantMessageComplete Callback = NULL);

 

Guid SendInstantMessage(Peer &Peer, ::std::string Message, int InstantMessageType = 0, SendInstantMessageComplete Callback = NULL);

 

Example of send instant message request:

CM->SendInstantMessage(OtherPeer,"Hi man!",YourApplicationMessagesEnum::TextMessage);

You notice all have optional argument to InstantMessageType used to distinguish them, for example you have number of control messages and text messages so this gives you easy way to distinguish them.

You also notice there is callback argument . That callback will trigger when message is delivered to your super-node, it does not mean it is delivered to other peer when callback triggers. Message will travel to destination peer super node and then it will be delivered to it.

 

 6 Direct communication tunnel creation between peers

 

The main API feature and probably main reason why you use it is the ability to create direct communication channels between two computers  that are both behind NAT (router) devices using NAT traversal techniques. The main advantage of this API is that as a result you will get standard platform socket to use from then on. System will self inspect what is the best method of tunnel criterion between two peers and create it. So you don't need to know anything  about STUN, NAT port mapping prediction, UPnP, NAT  PMP, PCP... or anything else that happens in the background and just wait for your prepared socket.

(Note - special situations when both peers are on same local network or even on same computer are handled by API so data will be transferred locally in that case not going over the Internet ) .

In past texts we talked about how to find some peer. When you know that, and you want to open direct communication channel you initiate connect request. On the other side peer needs to accept this request so handshake procedure could start.

You need this two event handlers:

//When we make connect request (tunnel creation) we wait for operation completion to trigger event

CM->onPeerConnected += new qp2plib::DelegateStatic<qp2plib::Peer*,qp2plib::Guid*>(onPeerConnectEventHandler,true);

 

//When some other peer initiate tunnel creation to us, operation completion will trigger event

CM->onPeerAccepted += new qp2plib::DelegateStatic<qp2plib::Peer*,qp2plib::Guid*>(onPeerAcceptEventHandler,true);

.....

 

//After successful connect operation this handler is triggered

void onPeerConnectEventHandler(qp2plib::Peer *remotePeer,qp2plib::Guid * transactionUID){

{

   // remotePeer->TunnelSocket is tunneled socket ready for data transfer

   char *tunneled_message = "Hello through tunnel!" ;

   send(remotePeer->TunnelSocket,tunneled_message,strlen(tunneled_message),0);

 

   //do something else

}

.....

//THIS WILL TRIGGER WHEN OTHER SIDE CALL cm.connect(... TARGETING LOCAL PEER

void onPeerAcceptEventHandler(qp2plib::Peer *remotePeer,qp2plib::Guid * transactionUID){

 {

   // remotePeer->TunnelSocket is tunneled socket ready for data transfer

   char buff[512];

   int read = recv(remotePeer->TunnelSocket,buff,512,0);

   char *tunneled_message = "Hello through tunnel to you to!" ;

   send(remotePeer->TunnelSocket,tunneled_message,strlen(tunneled_message),0);

   //do something else

}

 

One peer initiates connect request  that would in this case use event handlers that look like this:

qp2plib::Guid transactionUID = CM->Connect(OtherPeers,qp2plib::CT_TCP);

 

 

and on completion void onPeerConnectEventHandler(qp2plib::Peer *remotePeer,qp2plib::Guid * transactionUID) would trigger on his side. On other side void onPeerAcceptEventHandler(qp2plib::Peer *remotePeer,qp2plib::Guid * transactionUID)  would trigger on a side of peer accepting connection.

 

 if you need to control access - how it can connect  and how it cannot, you can override Accept Connection Reslover by providing your resolver function:

....

void onDecideToAcceptPeerConnection(qp2plib::ConnectionManager* sender,qp2plib::Peer* fromPeer, qp2plib::ConnectionType connType ,bool* result){

       if(???your condition to accept tunnel creation???)

        (*result) = true;

    else

        (*result) = false;

}

....

qp2plib::DelegateStatic<qp2plib::ConnectionManager*,qp2plib::Peer*, qp2plib::ConnectionType,bool*>

acceptResolveDelegate (onDecideToAcceptPeerConnection,false);

 

....

int main(int argc, char* argv[]){

....

CM->SetAcceptPeerConnectionResolver(&acceptResolveDelegate);

....

 

Note we set deleteAutomaticaly = false because we used static stack allocation in this case. Static allocation is good for this case because for  acceptResolveDelegate we would not worry about deleting object, if we would use dynamic allocation with 'new' we would also need to set deleteAutomaticaly = false because we can expect that will execute multiple times during application lifetime and letter we would need to kill it with delete statement manually.

 

By default all connection request will be accepted unless  you set CM->BlockIncoming = true;

 

Tunnel  accept/connect using callbacks would look like this:

 

SIDE THAT DOES CONNECT:

void onPeerConnectCallback(qp2plib::Peer *remotePeer, qp2plib::Guid *PeerCheckpointUID, qp2plib::Guid *PeerUID, qp2plib::Guid *transactionUID, bool success, qp2plib::ConnectionManager::PeerConnectFailureReason reason){

              if(success){

                     // remotePeer->TunnelSocket is tunneled socket ready for data transfer

                     char *tunneled_message = "Hello through tunnel!" ;

                     send(remotePeer->TunnelSocket,tunneled_message,strlen(tunneled_message),0);

              }else

                     printf("\nNAT Travesal operation failed");

              }

};

....

//invoke connect

CM->Connect(

              remotePeer,

              qp2plib::CT_TCP,

              qp2plib::IPEndPoint::ANY(),

              new qp2plib::DelegateStatic<qp2plib::Peer*, qp2plib::Guid*, qp2plib::Guid*, qp2plib::Guid*, bool, qp2plib::ConnectionManager::PeerConnectFailureReason>( onPeerConnectCallback,true,true));

 

SIDE THAT DOES ACCEPT:

 

void onPeerAcceptCallback(qp2plib::Peer *remotePeer, qp2plib::Guid *PeerCheckpointUID, qp2plib::Guid *PeerUID, qp2plib::Guid *transactionUID, bool success, qp2plib::ConnectionManager::PeerConnectFailureReason reason){

       // remotePeer->TunnelSocket is tunneled socket ready for data transfer

       char buff[512];

       int read = recv(remotePeer->TunnelSocket,buff,512,0);

       char *tunneled_message = "Hello through tunnel to you to!" ;

       send(remotePeer->TunnelSocket,tunneled_message,strlen(tunneled_message),0);

       //do something else

}

 

 

some ware in CM preparation like in int main(....

 

CM->PeerAccepted = new qp2plib::DelegateStatic<qp2plib::Peer*, qp2plib::Guid*, qp2plib::Guid*, qp2plib::Guid*, bool, qp2plib::ConnectionManager::PeerConnectFailureReason>(

               onPeerAcceptCallback,

               false

              );

 

Note we set deleteAutomaticaly = false because we can expect that  callback would execute multiple times during application lifetime so we don't want to delete delegate automatically after first execution. We would need to delete  CM->PeerAccepted with delete statement at program end in this case or we could use static allocation like this:

 

Some ware as global variable where onPeerAcceptCallback function is visible in scope:

 

qp2plib::DelegateStatic<Peer*, Guid*, Guid*, Guid*, bool, PeerConnectFailureReason> acceptDelegate(onPeerAcceptCallback,

               false);

 

then some ware in CM preparation like in int main(....

 

CM->PeerAccepted = &acceptDelegate;

 

Note that events handles are executed in one of 3 API threads  so long running tasks in handler body can block API. Read under:  "Connection manager  and result acceptance handlers/callbacks " text on how to handle that if you haven't done so already.

 

There is nothing special we need to talk about this, you have a ready socket so you do what you want with it from then on. Just have in mind that you are responsible for socket from then on so you need to close it when you no longer need it. Also as a good practice to follow is that you can just save that socket when you finish the task for new use if needed. So if you need do new task involving data transfer with that same peer you can just pool out that socket instead of invoking tunnel creation again (1-15sec).  You can destroy such socket when you leave application or if that peer goes offline.

 

 7 Using virtual index storage

 

Since quickP2P system goal is to provide you complete environment so you could focus just on application we introduced permanent index storage sub-system. We figured out that it would be convenient to provide way to store and be able to search some commonly used things like user registration data that is more  closely aware of peers. You don't need to use this sub-system if you have your own in mind. You would just need some key you would store in peer properties to associate peers with your objects later.

You can imagine index system  as remote database with two tables User and Network. Of course these are not ordinary tables that have fixed columns. You can store whatever property (name, value)  you need and later search them. Besides common operations like SELECT/INSERT/UPDATE/DELETE what is most important is that User object is aware which peers are authenticated with it. Multiple peers can be authenticated with single user object and also open peer can be authenticated with multiple user objects. Both user and network object have UID and custom property bag. Constrains are that User object must have "Username" property and Network object needs to have "Name" property. There cannot be two User objects with same username in your application scope and same stands for name for networks. If you somehow need to enable different situation for some reason you can generate these properties in some special way based on some other property. 

User object has columns "Member of networks" because you can join/un-join some user from network and "Currently bound Peers" which holds list of currently bound peer UIDs. User object also has password property you cannot see in provider portal.

Object used for virtual index management is cm.VNIndexManagerAll index operations complete synchronously because there are no critical time dependent functions . If you need asynchronous execution you need to implement it.  Also if there is something wrong exception is thrown.

This is list of all Virtual index manager operations:

qp2plib::VUser SaveUser(qp2plib::VUser &user,::std::string user_password = "");

- Inserts or updates virtual user. You pass user object you want to save and save it providing password for that user.  If VUser UID property is 00000000-0000-0000-0000-000000000000 system will do INSERT otherwise it will do UPDATE.  Result of operation is fresh User object like on index server in that moment this also meant PeerUIDS property will have fresh list of authenticated peers. So if UID was empty UID will get some real value from server after operation completes.

This would be code to create new user:

 

qp2plib::VUser newUser;

newUser.Username("some_username");//THIS IS REQUIRED, IT IS ALIAS FOR newUser["username"]

newUser["name"] = "Mike";

newUser["email"] = "This email address is being protected from spambots. You need JavaScript enabled to view it.";

newUser = CM->VNIndexManager()->SaveUser(newUser, "somepassword");

 

 if (newUser.UID != qp2plib::Guid::Empty()) {

   printf("User is saved , assigned UID is: %s",newUser.UID.ToString().c_str());

}

 

then update operation would be:

newUser["name"] = "Mike2";

newUser = cm.VNIndexManager->SaveUser(newUser, "somepassword");

Note that after this operation in case of creating new user PeerUIDS property  will be empty. Peer need to call in AuthenticateUser  method in order to have his UID appearing in this list.

VUser AuthenticateUser(::std::string Username, ::std::string Password);

- Checks for existing username with password and if it exists adds peer UID to VUser PeerUIDSlist , then returns VUser object:

qp2plib::VUser u;

...

u = CM->VNIndexManager().AuthenticateUser("some_username""somepassword");

If you perform AuthenticateUserand user is already authenticated that is not bad operation. It will not have side effects and you can use it to get fresh VUser object from index server. 

 

void QueryUsers(::std::list<qp2plib::VUser> *result_list, ::std::string QueryCommandText, int skip = 0, int limit = 0, ::std::string ascOrderBy = "", ::std::string descOrderBy = "");

 

- Searches for VUsers matching query , adds list of found VUsers to provided result_list

CM->VNIndexManager()->QueryUsers(&list_to_fill,"\"Properties.City\":\"Palo Alto\"");

If you expect large number of objects to be returned consider using pagination. In last two optional  parameters you enter comma separated property names .

 

long QueryUsersCount(::std::string QueryCommandText);

 

- Searches for VUsers matching query , then returns number of objects found

 

void DeleteUser(qp2plib::Guid userToDeleteUID);

 

- Deletes VUser object having exact UID:

 

cm.VNIndexManager.DeleteUser(u.UID);

 

 void ChangeUserPassword(qp2plib::Guid userUID, ::std::string old_password, ::std::string new_password);

 

- Changes VUser object password. Passwords are not visible to anyone. In case that user forgets  password and wants to reset it, you need to use magic value:

 (requesterPeerUID.ToString() + ApplicationUID.ToString() + userUID.ToString()).ToLower()

for old password to be able to reset it.

 

void JoinUserToNetwork(qp2plib::Guid userUID , qp2plib::Guid networkUID);

 

- Updates NetworkUIDS list on index server in VUser object identified by userUID argument by adding provided networkUID. You need to update your local VUser object manually after that or to reload.

 

void UnJoinUserFromNetwork(qp2plib::Guid userUID, qp2plib::Guid networkUID);

 

- Updates NetworkUIDSlist on index server in VUser object identified by userUID argument by removing provided networkUID. You need to update your local VUser object manually after that or to reload it.

qp2plib::VUser LogOffUser(::std::string Username);

- Removes  Peer UID from  PeerUIDSlist in VUser object on index server. Returns fresh copy of VUser object.

qp2plib::VNetwork SaveNetwork(qp2plib::VNetwork &network);

- Inserts or updates (based on UID value) VNetwrok object. If UID is empty insert will be performed. Result is fresh copy of VNetwork object from index server.

 

VNetwork newNetwork;

newNetwork.Name("network1");//THIS IS REQUIRED, IT IS ALIAS FOR newNetwork["name"]

newNetwork["owner"] = "Mike";

newNetwork = CM->VNIndexManager()->SaveNetwork(newNetwork);

 

 if (newNetwork.UID != qp2plib::Guid::Empty())

{

    printf("Network is saved , assigned UID is: %s", newNetwork.UID.ToString().c_str());

}

 

then update operation would be:

newNetwork ["owner"] = "Jeff";

newNetwork = CM->VNIndexManager()->SaveNetwork(newNetwork);

there cannot be to networks with same name in application scope.

 

void DeleteNetwork(qp2plib::Guid networkToDeleteUID);

- Deletes VNetwork  object having exact UID:

CM->VNIndexManager()->DeleteNetwork(n.UID);

 

 void QueryNetworks(::std::list<qp2plib::VNetwork> *result_list,::std::string QueryCommandText, int skip = 0, int limit = 0, ::std::string ascOrderBy = "", ::std::string descOrderBy ="");

 

- Searches for VNetworks matching query , then returns list of found VNetworks  to requester

CM->VNIndexManager()->QueryNetworks(&result_list,"\"Properties.Interes\":\"Ecology\"");

If you expect large number of object to be returned consider using pagination. In last two optional  parameters you enter comma separated property names .

 

long QueryNetworksCount(::std::string QueryCommandText);

 

- Searches for VNetworks matching query , then returns number of objects found

qp2plib::VObject SaveObject(qp2plib::VObject &obj);

- Inserts or updates (based on UID value) VObject object. If UID is empty insert will be performed. Result is fresh copy of VObject object from index server.

 

VObject newObject;

newObject["something"] = "[\"1\",\"2\",\"9\"]";

newObject = CM->VNIndexManager()->SaveObject(newObject);

 

 if (newObject.UID != qp2plib::Guid::Empty())

{

    printf("Object is saved , assigned UID is: %s", newObject.UID.ToString().c_str());

}

 

then update operation would be:

newObject["something"] = "[\"1\",\"2\",\"9\",\"15\"]";

newObject = CM->VNIndexManager()->SaveObject(newObject);

 

 void DeleteObject(qp2plib::Guid objectToDeleteUID);

- Deletes VObject  object having exact UID:

CM->VNIndexManager()->DeleteObject(newObject.UID);

 

 void QueryObjects(::std::list<qp2plib::VObject> *result_list,::std::string QueryCommandText, int skip = 0, int limit = 0, ::std::string ascOrderBy = "", ::std::string descOrderBy ="");

 

- Searches for VObject-s matching query , then returns list of found VObject-s  to requester

 

CM->VNIndexManager()->QueryObjects(&result_list("\"Properties.something\":\"15\"");

 

If you expect large number of object to be returned consider using pagination. In last two optional  parameters you enter comma separated property names .

 

long QueryObjectssCount(::std::string QueryCommandText);

 

- Searches for VObjectss matching query , then returns number of objects found

Note we used json array for newObject["something"value. Index server will automatically detect json array string shape or  json object string shape and store it in that form. It is important that you don't have blank characters before "[" or "{" in this cases because index server will not do object/array check in that case . This enables you full scale use of sub-objects in search queries.

You might need to have administrative application or site so you can give support to your user that can perform all index operation. When creating it have in mind that you must open session (become network  peer) to gain access to index server.

 

8 Security, key exchange and data encryption/decryption

 

QuickP2P API provides you easy way to obtain secure keys to be known only to peers involved with tunnel. You use this keys to crypt/decrypt data during data transfer.

Secure key exchange is based on "Diffie–Hellman"  algorithm with encampment to original concept. There is no "real" fixed key part, instead some short lived data existent for few seconds during handshake operation is used to generate what is called "Fixed part" in original concept.  This eliminates possibility for attacker knowing fixed part  to intrude data integrity using any encryption breaking theory.

32 bytes of security data is known only to two peers involved with tunnel. Security data is generated always during handshake procedure.  After each successful connect/accept , generated bytes can be obtained from handler function Peer argument object :

 

void on_PeerConnect(qp2plib::Peer *remotePeer,qp2plib::Guid * transactionUID){

       unsigned char key[16];

       memcpy(key,remotePeer->TunnelSecretData,16);

            ....

}

 

 void on_PeerAccept(qp2plib::Peer *remotePeer,qp2plib::Guid * transactionUID){

       unsigned char key[16];

       memcpy(key,remotePeer->TunnelSecretData,16);

            ....

}

quickP2P API has built-in classes that for AES encryption (chipering) .

AES class - core AES encryption

If support following AES variants:

Key size:

  • 128
  • 192
  • 256

Chipering mode :

  • ECB (each block crypt with key separately, commonly used when partial decryption is required )
  • CBC (default - each block is XOR-ed with previous crypted block then crypted with key. First 16 chunk is XOR-ed using CBCInitialVector. Single byte difference makes whole data unusable )

Padding:

  • None
  • PCKS7

AESNetworkStream - used to prepare data for crypt transfer when tunnel is stream based (TCP). AESNetworkStream is not standardized and its designed for easy use with quickP2P tunnels (you can use to else ware if both sides have it as first gate).  AESNetworkStream enables you to use CBC mode for real time communication because provides you ability to use fairly sized blocks crypt with CBC chipering. Normally in CBC mode you would need to get all data (like whole file)  , then decrypt it so you could use it.  AESNetworkStream can use more secure CBC mode and provide you partial data decryption.

For UDP datagrams you can simply use core AES class.  

One thing to note when working with this classes is that original and crypted data do not have same size. Crypted data is usually slightly larger than original. 

Next is simple example of crypting and decrypting text with core AES class:

 

       qp2plib::Guid g;

       unsigned char key[16];

       g.WriteToByteArray(key);//we generate some random key just for test

       qp2plib::AES a(qp2plib::AES::AESKS_Bits128,key, qp2plib::AES::AESPAD_PCKS7, qp2plib::AES::AESM_CBC);

       //we generate some test text and convert it to bytes

       const char *original = "Hello I'am text to crypt";

       int sLen = strlen(original);

       unsigned char buff1[512];

       //we crypt

       int cryptlen = a.Crypt((unsigned char*)original,0,sLen,buff1,0);

       unsigned char buff2[512];

       //we decrypt

       int dlen = a.Decrypt(buff1, 0, cryptlen, buff2, 0);

       //we convert bytes to text

       buff2[dlen] = '\0';

       const char *decrypted_text = (const char *)buff2;

 

This is same thing done with AESNetworkStream:

 

       qp2plib::Guid g;

       unsigned char key[16];

       g.WriteToByteArray(key);//we generate some random key

       qp2plib::AESNetworkStream ans( qp2plib::AES::AESKS_Bits128 , key);

      //we generate some test text

       const char * original = "Hello I'am text to crypt";

       int slen = strlen((const char*)original);

       //we write data to stream to be crypted

       ans.WriteForCrypt((unsigned char*)original,0,slen);

       unsigned char buff1[512];

       //we read crypted data form stream

       int len = ans.ReadCrypted(buff1,0,8192);

       //we now write crypted data for decryption

       ans.WriteForDeCrypt(buff1,0,len);

       unsigned char buff2[512];

       //we read decrypted data

       len = ans.ReadDeCrypted(buff2, 0, ans.AvailableDeCrypted());

       //we convert bytes back to text

       buff2[len] = '\0';

       const char* decrypted = (const char*)buff2;

 

Usually you also need to set CBC initial vector (commonly "IV" )  if you are using CBC mode.  quickP2P AES class will  generate it if not provided based on key value. In above example we didn't set it but it's recommended you do so. Both classes have means to provide you pointer to internal CBC internal vector buffer you can set bytes before you do any crypt/decrypt operation.

 

 9 Add firewall exception  for your application in application installer

 

It's recommended that you add firewall exception  in local OS for your application. Communication will find its paths anyway but firewall exception  can drastically increase performance.  While developing you can do that manually but you would probably need a way to do that on user computers. This is generally most important for Windows operating systems because for other system this API version is used mostly this is defined in app bundle itself or system ask once user to allow this behavior so there is no need to do anything.