PIDL

Creating and setup

Creating the file is simple. Simply create the file in Visual Studio as a txt file, rename the extension to PIDL, and set it up for compilation. Files with the PIDL extension must be set to Custom Build.

  1. Visual Studio solution Viewer

  2. Right-click the PIDL file you created

  3. Properties -> General -> Item Type: Custom Build Tool

PIDL syntax

The PIDL is structured as follows.

global (namespace) 
         (starting value of the message's ID) 
{ 
     Declaring function([in] function Parameter, …) 
}

When compiling, a namespace is created and the Stub and Proxy Class are placed within this namespace. All RMI functions have a unique ID, and this value is given by adding +1 from the ‘starting value of the message's ID’. However, ID between 0 and 1,300 and ID above 63,000 are used in ProudNet internal messages, so you must use other numbers.

// Define variables that need to be reformatted for use in C#.
rename cs(Proud::String, System.String);

global S2C 1000 
{
     // Define the Protocol.
    Chat([in] Proud::String txt);
}

How to use the generated Proxy & Stub file

When you run PIDL, it will generate six files as shown below.

  • PIDLfile name_Common.Cpp

  • PIDLfile name_Common.h

  • PIDLfile name_proxy.Cpp

  • PIDLfile name_proxy.h

  • PIDLfile name_stub.Cpp

  • PIDLfile name_stub.h

For C#, this will create 3 files as shown below.

  • PIDLfile name_common.cs

  • PIDLfile name_proxy.cs

  • PIDLfile name_stub.cs

It is convenient to #include each h file in the header and each cpp file in the cpp file, except for the Common file. You can include the .h and .cpp files in your project, but be aware that the files change frequently due to the use of Custom Build. The generated RMI function automatically adds two parameters in addition to the variables you define.

- Attach a proxy to a client and server

You must first create a Proxy instance of the PIDL compilation output and then register the instance with either Proud.CNetClient or Proud.CNetServer. Clients and servers inherit from Proud.IRmiHost and can register a proxy with it via the method AttachProxy. Each client or server can attach more than one Proxy. However, the range of message IDs must not overlap.

Similarly in C#, you can use the AttachProxy function found in NetServer and NetClient.

For example, if you have TestA.Proxy and TestB.Proxy attached to a single CNetClient, and you declare the first message ID of TestA to be 2,100 and the first message ID of TestB to be 2,200, if the number of RMI functions declared in TestA is 200, the message ID assigned to TestA will be between 2,100 and 2,300, causing the message IDs of TestB to overlap. If the message IDs of the attached proxies overlap, an exception is thrown.

- Attach a stub to a client and server

// If you are using C++11
<exam.pidl>
Func1([in] int a, [in] string b);
 
<exam.cpp>
class Exam
{
    int x = 1;
 
    Exam::StubFunction examStub;
 
    void Main()
    {
        int y = 3;
        // PARAM_Exam_Func1 is a define defined in Exam_stub.h.
        examStub.Func1_Function = [this, y]PARAM_Exam_Func1 {
            x += a;
            y += a;
            return true;
        };
    }
};

The Stub instance of the PIDL compilation result has the RMI functions to be executed by messages received over the network as virtual function. When developing, you must inherit this Stub class and override the RMI functions.

In C#, you can create and use the Stub object directly without any overrides.

For the convenience of C++ developers, the PIDL compiler generates the following types of macros, packaged with RMI function names and parameters.

#define DECRMI_S2C_ShowChat bool ShowChat(Proud::HostID remote,Proud::RmiContext &rmiContext,const CString &a,const int &b,const float &c)
#define DEFRMI_S2C_ShowChat(DerivedClass) bool DerivedClass::ShowChat(Proud::HostID remote,Proud::RmiContext &rmiContext,const CString &a,const int &b,const float &c)

- Order of macro

// Order of macro use
// 1. In the class declaration of the inherited Stub class, add the DECRMI_Namespace_Method.
// 2. Use DEFRMI_Namespace_Method in the method definition of the inherited Stub class.

// Usage examples

// PIDL file content
global LobbyC2S 5000
{
    Foo([in] int a,[in] float b);
}
 
// Classes that inherit from LobbyC2S's stub to implement RMI
class LobbyC2SStub:public LobbyC2S::Stub
{
    DECRMI_LobbyC2S_Foo;
};
 
// Implementing Routines in RMI Foo in LobbyC2S
DEFRMI_LobbyC2S_Foo(LobbyC2SStub)
{
    // The parameters given here are the same as those in LobbyC2S.Foo in the PIDL.
    a++;
    b++;
 
    return true;
}

Clients and servers inherit from Proud.IRmiHost and can register a stub via the method Proud.IRmiHost.AttachStub in it. As with proxies, more than one stub can be attached as long as the message IDs do not overlap.

- Option Class for Communication

It is convenient to use variables declared as internal static.

C++
C#
Description

Proud::HostID

Nettention.Proud.HostID

The ID of the host you want to communicate with

Proud::RmiContext

Nettention.Proud.RmiContext

Options for sending or receiving

Reliable / Unreliable Communication name
Description

ReliableSend

Reliable communication

FastEncryptedReliableSend

Reliable communication using fast encryption method (less secure)

SecureReliableSend

Encrypted reliable communication

UnreliableSend

Unreliable communication

FastEncryptedUnreliableSend

Unreliable communication using fast encryption method (less secure)

SecureUnreliableSend

Encrypted unreliable communication

The most commonly used options are pre-built as Static. You can create your own options to suit your needs.

m_reliability: Selecting Reliable & Unreliable communication methods m_encryptMode: Whether to encrypt (there are three options, depending on speed and security) m_compressMode: Whether to compress

In C#, use a variable defined with the same name.


Usage

Utilization of PIDL

Last updated