Using the Client and Server API

Parent page: Using the Altium Designer API

Using the Client and Server Interfaces

The client module is represented by its IClient interface object and you have the ability to take a peek into the data structures through this IClient interface. The client maintains a list of loaded servers, opened server documents, loaded server processes and resources. Servers are represented by IServerModule interfaces.

Client function

The Function Client : IClient; returns the Client interface object within your server project. With this object interface, you can extract extra information about the client module and its associated servers.

Using the Client function in a script

Var
    CurrentView : IserverDocumentView;
Begin
    CurrentView   := Client.CurrentView;
    If CurrentView <> Nil Then
        OwnerDocument := Client.CurrentView.OwnerDocument;
End;

IClient and its main composite Interfaces

• IClient (the interface of the Client subsystem) and a few of its main composite interfaces
• IServerModule (the Client has a handle on servers loaded in memory)
• Notification (the Client can broadcast notification messages to servers)
• ICommandLauncher (deals with launching a server command)
• IProcessControl (determines the level of stacked processes for an opened document)
• IGUIManager (deals with the Altium Designer User Interface, the locations and state of panels)
• IServerDocumentView (deals with the current view as panels and documents in Altium Designer)
• IOptionsManager (deals with system wide Preferences dialog in Altium Designer)
• IServerRecord (information of server installation files in the \System folder)
• IServerPanelInfo (panels information)
• IOptionsManager (Manage Option pages for each server)

IServerModule and its main composite Interfaces

• IServerModule (deals with the shell of the server module)
• IServerView (represents a system panel that can have a view of the Altium Designer system)
• IServerDocumentView (represents a document view)
• IServerDocument (represents a container of documents of the same type for a server)
• IProcessControl (determines the level of stacked processes for this focussed server document)
• INotification (a server can receive notifications from the Client system).
• ICommandLauncher (deals with launching server commands)

For detailed information see the Technical Reference - System API.

Workspace Manager Interfaces

The Workspace Manager is a system extensions server which is always running when Altium Designer is loaded in memory. The Workspace Manager provides project functionality of grouping of files and provides a bridge between source documents (such as Schematic documents) and its corresponding primary implementation documents (such as PCB documents).

This Workspace Manager provides information on how a project is structured, information on nets and its associated net aware objects of source and implementation documents. This Workspace Manager also provides you with the ability to manipulate the contents of a design project in Altium Designer.

The document interfaces in the Workspace Manager can refer to documents which may not be open in Altium Designer whereas, the IServerDocument interfaces only references loaded documents in Altium Designer.

The Workspace Manager object derives some of its functionality from the Workspace interface. To have access to data within the Workspace Manager, you need to have access to the IWorkSpace interface object, which references the workspace manager.

Simplified Workspace Manager Object hierarchy

IWorkspace
      IProject
            IDocument
                  ISheetSymbol
                  IComponent
                  IBus

Main Workspace Manager Interfaces

• The IDMObject interface is the ancestor interface used for many Workspace interfaces.
• The IWorkSpace interface is the top level interface and contains many interfaces within. For example the IWorkSpace interface has a DM_OpenProject function which returns a currently open or currently focussed IProject interface.
• The IProject interface represents the current project in Altium Designer.
• The IPart interface represents a part of a multi-part component. This component is represented by this IComponent interface.
• The IDocument interface represents a document in Altium Designer.
• The IComponentMappings interface is used for the Signal Integrity models mapping to Schematic components.
• The IECO interface represents the Engineering Change Order system in PCB and Schematic editors.
• The INet interface is a container storing Net aware objects (which are INetItem interfaces) that have the same net property. So there are INet interfaces representing nets on a document.
• The INetItem interface is the parent interface for the Cross interface. Pin, Port, Netlabel, Sheet entry and Power Object Interfaces are direct representations of the INetItem interface so these objects can be part of a net.

GetWorkspace function

The Function GetWorkspace : IWorkspace; returns the Workspace Manager interface object within your server project. With this interface, you can extract extra information about a project and its associated documents and their design objects on them.

Using the GetWorkSpace function in a DelphiScript

Var
    i        : Integer;
    Document : IDocument;
    Project  : IProject;
Begin
    Project := GetWorkspace.DM_FocusedProject;
    If Project = Nil Then Exit;
    For i := 0 To Project.DM_LogicalDocumentCount - 1 Do
    Begin
        Document := Project.DM_LogicalDocuments(i);
        ShowMessage(Document.DM_DocumentKind);
    End;
End;

Check out the DXP server examples in the Scripts\DelphiScript Scripts\DXP\ folder.

Compiling a project

A project needs to be compiled first so you can have access to the most current data which provides a snapshot of the latest status of a design project. There are two ways you can compile the project which are shown below.

Compile with Project.DM_Compile example

Procedure CompileProject;
Begin
    Project := GetWorkspace.DM_FocusedProject;
    If Project = Nil Then Exit;
    Project.DM_Compile;
    FileName := Project.DM_ProjectFullPath;
End;

Compile example using the MessageRouter_SendCommandToModule call

GetMem(P, 4048);
SetState_Parameter(P,'Action','Compile');
SetState_Parameter(P,'ObjectKind', 'Project');
MessageRouter_SendCommandToModule('WorkspaceManager:Compile',P,4048,Nil);
FreeMem(P);

For detailed information on Workspace Manager API, refer to the Technical Reference - Workspace Manager API document.
Check out the script examples in the Scripts\DelphiScript Scripts\DXP\ folder of your installation.

Nets of design documents

Schematic Design documents that have components and wires contain connectivity information which is captured in nets. A net is composed of connections and each connection is linked by a node as a pin. Nets are connected pins and a valid net has more than 1 pin.

To obtain connectivity information, we use the WorkSpace Manager API to fetch net information. Open a project with valid schematics and then going through each schematic, the net count is obtained and for each net, the pin count is obtained and we have pins at our disposal. With pin interfaces, we can fetch pin designator, pin number and so on.

The design project needs to be compiled first, the documents (IDocument interfaces) are obtained and then the Nets (INet interfaces) are obtained. For each net, IPin interfaces are again obtained.

Fetch Nets example using the INet interface

//net information is stored in the NetList TStringList container
For i := 0 To Document.DM_NetCount - 1 Do
        WriteNet(Document.DM_Nets(i));
 
Procedure WriteNet(Net : INet);
Var
    I       : Integer;
    Pin     : IPin;
    PinDsgn : String;
    PinNo   : String;
Begin
    If Net.DM_PinCount >= 2 Then
    Begin
        NetList.Add('(');
        NetList.Add(Net.DM_CalculatedNetName);
        For i := 0 To Net.DM_PinCount - 1 Do
        Begin
            Pin := Net.DM_Pins(i);
            PinDsgn := Pin.DM_PhysicalPartDesignator;
            PinNo   := Pin.DM_PinNumber;
            NetList.Add(PinDsgn + '-' + PinNo);
        End;
        NetList.Add(')');
    End;
End;

PCB Design documents also have net information but these nets are captured in IPCB_Net interfaces. Refer to the Technical Reference - PCB API document for more information.
See the script examples in the Scripts\DelphiScript Scripts\WSM\ folder.