Code Examples

CNQMessage reference pointer usage

This is an example of issuing an RPC-like call. It shows how to handle CNQMessage reference pointer, CNetworkQueue::create(), CNetworkQueue::freeMsg() and CNetworkQueue::sendRecvMsg().

Communication Scheme

Example Code of RPC-call

    #include "NQ.h"

    CNetworkQueue nq;
    // Initialisation of nq omitted
    ...
  
    bool        ret;                           // helper variable for return values
    CNQMessage *request, *response;            // Declare CNQMessage Pointers
    NQ_TIMEVAL  timeout;
    
    // set timeout of one second
    timeout.tv_sec = 1;
    timeout.tv_usec = 0;

    request = nq.createMsg();                  // request a new CNQMessage object reference
    
    if (request != NULL) {
        
        // configure packet type and fill with parameters 
        request->setType(NQ_PT_REQUEST, NQ_LT_CALL);
        ...                      
        
        // call CNetworkQueue:sendRecvMsg() 
        ret = nq.sendRecvMsg(&response, request, ip_hostorder_peer, port_hostorder_peer, timeout);
        
        if (ret==true) {
            // success! now handle with response CNQMessage
            ...
            
            // cleanup. free the CNQMessage reference, because we don't need it anymore
            nq.freeMsg(response);               
        } else {
            // ERROR: CNetworkQueue:sendRecvMsg() returned error
            //        now, handle the error
            ...
            
            // NOTE: we don't need to free response reference here, because it was not allocated
        }
        
        // free request reference, because we don't need it anymore
        nq.freeMsg(request);
    } else {
        // ERROR: CNetworkQueue::createMsg() did not return a valid CNQMessage reference pointer 
        //        now, handle the Error
        ...
    }    

Asynchronous sending

This is an example of quickly pushing out (asynchronous, without blocking) a telegram message. It uses CNetworkQueue::sendMsg() without timeout.

Communication Scheme

Example Code of asynchronous sending

    #include "NQ.h"

    CNetworkQueue nq;
    // Initialisation of nq omitted
    ...
  
    bool        ret;                           // helper variable for return values
    CNQMessage *telegram;                      // Declare CNQMessage Pointer
    
    telegram = nq.createMsg();                 // request a new CNQMessage object reference
    
    if (telegram != NULL) {
        
        // configure packet type and fill with parameters 
        telegram->setType(NQ_PT_REQUEST, NQ_LT_CALL);
        ...                      
        
        // call CNetworkQueue:sendMsgTo() 
        ret = nq.sendMsgTo(telegram, ip_hostorder_peer, port_hostorder_peer );
        
        if (ret==true) {
            // success! message should be sent out and received at remote peer
            // however, there is no guarantee!
            ...
            
        } else {
            // ERROR: CNetworkQueue:sendMsgTo() returned error
            //        now, handle the error
            ...
            
        }
        
        // free request reference, because we don't need it anymore
        nq.freeMsg(telegram);
    } else {
        // ERROR: CNetworkQueue::createMsg() did not return a valid CNQMessage reference pointer 
        //        now, handle the Error
        ...
    }    

Synchronous sending

This is an example of sending-with-acknowledge (synchronous, timeout blocking) a telegram message. It uses CNetworkQueue::sendMsg() with timeout.

Communication Scheme

Example Code of synchronous sending

    #include "NQ.h"

    CNetworkQueue nq;
    // Initialisation of nq omitted
    ...
  
    bool        ret;                           // helper variable for return values
    CNQMessage *telegram;                      // Declare CNQMessage Pointer
    NQ_TIMEVAL  timeout;
    
    // set timeout of one second
    timeout.tv_sec = 1;
    timeout.tv_usec = 0;
    
    telegram = nq.createMsg();                 // request a new CNQMessage object reference
    
    if (telegram != NULL) {
        
        // configure packet type and fill with parameters 
        telegram->setType(NQ_PT_TELEGRAM, NQ_LT_UPDATE);
        ...                      
        
        // call CNetworkQueue:sendMsgTo() 
        ret = nq.sendMsgTo(telegram, ip_hostorder_peer, port_hostorder_peer, timeout );
        
        if (ret==true) {
            // success! message should be sent out and received at remote peer
            // this is guaranteed!
            ...
            
        } else {
            // ERROR: CNetworkQueue:sendRecvMsg() returned error
            //        now, handle the error
            ...
            
            // NOTE: this does not mean that the message was not received at remote peer, it could
            // also be that the acknowledge packet ("got it") did not properly arrive (in-time) at local peer
        }
        
        // free request reference, because we don't need it anymore
        nq.freeMsg(telegram);
    } else {
        // ERROR: CNetworkQueue::createMsg() did not return a valid CNQMessage reference pointer 
        //        now, handle the Error
        ...
    }    

Receiving Loop

This is an example of a receiving loop. It shows how to handle CNQMessage reference pointer, CNQMessage::getSenderIPandPort(), CNetworkQueue::freeMsg() and CNetworkQueue::recvMsg() with timeout.

Communication Scheme

Example Code of receiving loop

    #include "NQ.h"

    CNetworkQueue nq;
    // Initialisation of nq omitted
    ...
  
    bool        ret, ret2;                     // helper variable for return values
    CNQMessage *inMessage;                     // Declare CNQMessage Pointer
    bool        bShutdown = false;
    
    NQ_TIMEVAL  timeout;
    
    // set timeout of one second
    timeout.tv_sec = 1;
    timeout.tv_usec = 0;
    
    while( !bShutdown )
    {
        ret = nq.recvMsg(&inMessage, timeout);

        if (ret == true)
        {
            UINT32 ipHostorderPeer, portHostorderPeer;
            // a packet was received from (any registered) remote peer
            
            // NOW: check where it came from, what are the contents and do something about it

            ret2 = inMessage->getSenderIPandPort(ipHostorderPeer, portHostorderPeer)
            if (ret2 == true) 
            {
                // compare ipHostorderPeer and portHostorderPeer if necessary

                // HERE: read out type and contents of packet, branch and react accordingly
            }


            // IMPORTANT: do not forget to put back CNQMessage instance after no longer needing it
            nq.freeMsg(inMessage);
            
            // DONT FORGET: any access to inMessage is invalid afterwards!
        }
    }