API Help
EPLAN API / User Guide / API Electrotechnical services / Messages
In This Topic
    In This Topic

    As API developer, you can add new electrotechnical messages to EPLAN and to write them to the message management. 

    In order to create a new message, add a class to your project, which implements the interface IMessage. 


    The IEplMessage interface declares 3 functions:

    1. The parameters of the function OnRegister() define the properties of the message and how it is registered in EPLAN.
    2. The function GetMessageText() returns -- on request of EPLAN -- the message text, which is displayed in dialogs.
    3. The function DoHelp() is called by the system, if EPLAN request help about the message.
    public class Message: Eplan.EplApi.EServices.IMessage
        public void OnRegister( ref IMessage.Region eRegionId, ref int iMessageId,
          ref IMessage.Classification eClassification, ref int iOrdinal)
            eRegionId = IMessage.Region.Externals;
            iMessageId = 25;
            eClassification = IMessage.Classification.Error; iOrdinal = 20;
        public System.String GetMessageText()
            // TODO: Provide text from resource in active GUI language
            return "Message text for %1!s! from Eplan.EplAddIn.Demo.Messages";
        public void DoHelp()
            new Decider().Decide(EnumDecisionType.eOkDecision, "DoHelp was called!", "Eplan.EplAddIn.Demo.Messages", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK);
            // TODO: activate help for this message
    Public Class Message
       Implements Eplan.EplApi.EServices.IMessage
       Public Sub OnRegister(ByRef eRegionId As IMessage.Region, ByRef iMessageId As Integer, _
                              ByRef eClassification As IMessage.Classification, ByRef iOrdinal As Integer) _
                              Implements Eplan.EplApi.EServices.IMessage.OnRegister
          eRegionId = IMessage.Region.Externals
          iMessageId = 25
          eClassification = IMessage.Classification.Error
          iOrdinal = 20
       End Sub 'OnRegister
       Public Function GetMessageText() As System.String Implements Eplan.EplApi.EServices.IMessage.GetMessageText
          ' TODO: Provide text from resource in active GUI language
          Return "Message text for %1!s! from Eplan.EplAddIn.Demo.Messages"
       End Function 'GetMessageText
       Public Sub DoHelp() Eplan.EplApi.EServices.IMessage.DoHelp
          new Decider().Decide(EnumDecisionType.eOkDecision, "DoHelp was called!", "Eplan.EplAddIn.Demo.Messages", EnumDecisionReturn.eOK, EnumDecisionReturn.eOK
       End Sub 'DoHelp ' TODO: activate help for this message
    End Class 'Message

    A registered message can be written to the message database with help of the MessageManager class. 

    Eplan.EplApi.EServices.MessageManager oMessageMgr = new Eplan.EplApi.EServices.MessageManager();
    Eplan.EplApi.DataModel.ProjectManager oPM= new Eplan.EplApi.DataModel.ProjectManager();
    Eplan.EplApi.DataModel.Project oProject= oPM.CurrentProject;
    if (oProject != null)
        Eplan.EplApi.DataModel.Page[] arrPages = oProject.Pages;
        Eplan.EplApi.DataModel.Function[] arrFunction= arrPages[5].Functions;
        Eplan.EplApi.DataModel.StorableObject oObject1= arrFunction[0];
        Eplan.EplApi.DataModel.StorableObject oObject2= arrFunction[1];
        oMessageMgr.AddMessage( oProject, Eplan.EplApi.EServices.IMessage.Region.Externals, 25,
         "XYZ", oObject1, false, oObject2, "Additional Text");
    Dim oMessageMgr As New Eplan.EplApi.EServices.MessageManager()
    Dim oPM As Eplan.EplApi.DataModel.ProjectManager = New Eplan.EplApi.DataModel.ProjectManager()
    Dim oProject As Eplan.EplApi.DataModel.Project = oPM.CurrentProject
    If Not (oProject Is Nothing) Then
       Dim arrPages As Eplan.EplApi.DataModel.Page() = oProject.Pages
       Dim arrFunction As Eplan.EplApi.DataModel.Function() = arrPages(5).Functions
       Dim oObject1 As Eplan.EplApi.DataModel.StorableObject = arrFunction(0)
       Dim oObject2 As Eplan.EplApi.DataModel.StorableObject = arrFunction(1)
       oMessageMgr.AddMessage(oProject, Eplan.EplApi.EServices.IMessage.Region.Externals, 25, "XYZ", oObject1, False, oObject2, "Additional Text")
    End If


    Overriding text of an existing message 

    It is not possible to change an existing verification by overriding it via API (by setting the same name and a higher Ordinal number). You can however override an existing message and by this change the standard message text to your own text. You need to implement a message with the dame number and region, but use a higher iOrdinal, e.g. 50. Other properties of the message are not influenced. 

    The following example shows, how to override the existing 007005 "Device without main function." message: 

    Copy Code
    /// This function returns the message text.
    /// One verification needs always exactly one message text.
    public string GetMessageText()
       return "This device has absolutely no main function!!!!";
    /// This is the registration function of the message belonging to the verification.
    /// Parameters:
    /// message region
    /// message number
    /// classification: error, message, or info.
    /// overload priority
    public void OnRegister(ref String strCreator, ref Eplan.EplApi.EServices.IMessage.Region eRegion, ref int iMessageId, ref Eplan.EplApi.EServices.IMessage.Classification eClassification, ref int iOrdinal)
       strCreator = "de.Eplan.Demo";
       eRegion = IMessage.Region.Devices;
       iMessageId = 5;
       eClassification = IMessage.Classification.Error;
       iOrdinal = 50; // higher than 20
    See Also