My first peer

Introduction

It's very easy to create a REDnet peer and make it alive. Basically, it's a three-step process:

• initialize the REDnet library
• create the peer
• start the peer

Initialize the REDnet library

Every REDnet-based application must call RNET::System::Initialize before calling any other method in the library. Thus, our tutorial starts with:

// 1. RNET initialization:
// -----------------------
//  Before creating any REDnet resources, you must first 
//  initialize the REDnet library by calling Initialize.

// Upon initialization, REDnet returns the name of the host machine with the
// list of all detected network adapters.
if( RNET::System::Initialize( host_name, host_adapters ) != RED_OK )
{
  printf( "Error: REDnet failed to initialize.\n" );
  return RED_FAIL;
}

This has two effects: it initializes the OS-dependent network libraries and it gathers information about the network hardware. Those information are returned through two user-defined variables:

RED::String host_name;                      // name of the host machine.
RED::Vector< RNET::Adapter > host_adapters; // list of the network adapters available on the host machine.

By default, REDnet initializes itself using the first network adapter returned in the list. But you are free to use any other detected network adapter you want by calling RNET::System::SetAdapter. If you want to run locally without using any hardware adapter, you can look for a loop-back adapter in the returned list of adapters and pass it to RNET::System::SetAdapter.

Here, we continue with the default network adapter and display both its name and the host machine name:

// By default, REDnet is initialized with the first network adapter. So, display
// the adapter name and IP address.
printf( "Network adapter: %s\n", host_adapters[0].GetDescription().Buffer() );
printf( "IP address     : %s\n", host_adapters[0].GetAddress().ToString().Buffer() );
printf( "\n" );

We also use the adapter network address filled by the call to RNET::System::Initialize to get additional information about the network configuration of the host machine (like the IP v4 address for example).

REDnet is now initialized and ready to use.

Create the peer

As for any Redsdk object, REDnet objects are created and deleted through the RNET::Factory (RED::Factory in case of Redsdk objects):

// The REDnet peer creation process must go through the RED::Factory class.
RED::Object* peer = RED::Factory::CreatePeer();
if( peer == NULL )
{
  printf( "Error: REDnet failed to create the peer.\n" );
  RNET::System::Shutdown();
  return RED_FAIL;
}

Start the peer network code

The peer is created and set-up but not active yet. To make it "visible" to other network peers and to the REDnet dispatcher "dispatcher", we need to call:

// As any other object in REDsdk, you must query interfaces to raw objects
// before using them in a specialized way.
RNET::IPeer* ipeer = peer->As< RNET::IPeer >();

// Start the peer.
if( ipeer->Start( RED::Object::GetIDFromString( "MyFirstPeer" ), 1, "" ) != RED_OK )
{
  printf( "Error: REDnet failed to start the peer.\n" );
  RNET::System::Shutdown();
  return RED_FAIL;
}

In its most basic form, a peer is just a very simple network object which passively waits for input data on its communication port and can handle simple administration requests from a dispatcher. Here, we created the simplest peer ever: an ID, a version and a path to additional files. ID and version are required to uniquely identify the peer over the network when commuicating with it. The path to additional files is used when answering to HTTP get file requests. When not set, it points to the current application directory.

When RNET::IPeer::Start is called, a single thread is created to process the peer in the background of the application. Thus nothing more has to be done to set-up or manage a peer!

Cleaning everything

The tutorial ends by destroying the peer and shutting down the REDnet library:

// Delete the peer.
if( RED::Factory::DeletePeer( peer ) != RED_OK )
{
  printf( "Error: REDnet failed to delete the peer.\n" );
}

// Before exiting, REDnet needs to be shutdown properly.
RNET::System::Shutdown();

In the Registering to the dispatcher "next tutorial", we'll see how to connect to the dispatcher to make our peer available to network clients.

REDnet tutorials

Registering to the dispatcher