Table of Contents

 

Abstract 1

What is this ActiveX control for? Audience. 2

Installation. 2

Pre-Requisites. 2

Object Architecture. 3

Functional Description. 4

Programming Tips & Techniques. 4

Known Bugs & Pending. 5

Acknowledgements. 6

Version Information. 6

Disclaimer and License Statement 7

 

 

Abstract

 

AGWAPI is suite to implement under Windows 95/98/NT programming tools that enables the usage ofr the AGW Packet Engineâ. from any programming environment that supports the technology, primarily C++, Visual Basic and Delphi 5.

 

This is performed thru two very closely related components:

 

·        AGWAPI which is a Delphi 5 VCL that implements the class TAGWAPI.

·        AGWAPIX which is an ActiveX control that implements the class AGWAPIX.

 

Actually, the ActiveX component is directly derived from the VCL component thru the usage of the Inprise’s Delphi 5 ActiveX control wizard.

 

This control encapsulates the functionality to access the AGW Packet Engine using either a high and lower level approach.

 

The application programmer could choose to which level he wants to interact with the AGW Packet Engine.

 

The control allows to:

 

• Send and Receive information to the AGW Packet Engine, both connected and unconnected (UNPROTO).
• Management of Raw frames for non standard implementations using the AX.25 protocol.
• Manage the status of the AGW Packet Engine.
• Obtain monitoring information from the radio ports.
• Implement Connection Control, Digipeater and Beacon.

 

 

What is this ActiveX control for? Audience.

 

Both the VCL component and the ActiveX control are intended for both the beginner and the seasoned programmer that is willing to develop software for the AGW Packet Engine with a minimum of effort and focusing on the functionality he or she wants to implement rather than the details on how to implement it.

 

It provides a one-step, drag & drop, facility to plug-in into new or existing programs developed with any major language for the Windows environment, that includes Delphi 5 (either the VCL or the ActiveX control), MS Visual C++ (ActiveX) or Visual Basic (ActiveX).

 

Installation

 

To install the program the following actions has to be performed:

• UnZip the distribution file AGWAPInn.ZIP (nn=version) into a directory of your choice (i.e. C:\AGWX).
• Proceed with the instructions of your language of choice to import ActiveX controls.

 

The ActiveX control comes on a file named AGWXnn.ZIP (nn=version), also follow the instructions of your development environment to install and register a new ActiveX control.

 

 

 

 

Pre-Requisites

 

The AGWPE version required is 2000.70 or later, it won’t work with versions prior to that, so if you have a prior version or you are not sure what version you have just play safe and download a fresh version from SV2AGW’s Home Page

 

The program itself could run on either Windows 95, Windows 98, Windows NT, Windows 2000 and (probably) on Windows ME, still, the main requisite is to have AGWPE up and running on the target platform you’re planning to use.

 

 

 

Object Architecture

 

The object architecture is as follows:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

	MS C++ MS VB Delphi 5 …..
				Delphi 5 IDE

 

 

 

 

The components relies on four low level objects whose details are keep private from the programmer that interacts to implement the different functions required to use the AGW Packet Engine at various levels of functionality.

 

Those four components are:

 

• The main controlling object (AGWL2) which actually talks with AGW PE using the WinSocks API.
• The digipeater object (L2Digi) which actually process monitored raw frames to detect digipeater actions.
• The beacon object (L2Beacon) which takes care of the timming to send beacon messages.
• The AX.25 Link Manager object (L2Link) which actually encapsulates the functionality required to keep many simultaneous connections thru a single interaction with AGW PE.

 

All objects are “wrapped” into a VCL component that manages the export of the published methods, properties and events in a consistent and uniform way; this wrapper is also responsible to interact with the Delphi 5 IDE when the VCL is used and take care of VCL registration issues.

 

Using the Inprise’s ActiveX technology the VCL is seamlessy (plus or less) transformed into an ActiveX control.

 

The conversion wizard basically achieves this “magic” thru the following actions (which is good to understand in order to understand some of the subtle differences between both components).

 

• A COM library is created and all major interfaces created.
• For all properties on the VCL component both a “getter” and a “setter” function is created which is then mapped as part of the ActiveX interface.
• For all events of the VCL components a wrapper event is created and plugged into the corresponding events of the VCL.
• For all methods an entry on the exported interface is created and directly plugged (plus or minus some data type tweaking) into the corresponding methods of the VCL component.

 

 

 

 

 

Functional Description

 

The ActiveX Control AGWAPIX is a wrapper of several objects which presents a consistent interface to the programmer.

All internal objects had been developed using Inprise’s Delphi 5 VCLs, but that should be transparent to the final programmer; as such the ActiveX control should be able to be accessed from any major Windows programming 32 bits environment such as C++, Visual Basic or, of course, Delphi 5.

The different functions of the ActiveX control are segregated as:

 

·        Properties.

·        Methods.

·        Events.

 

Thru the selective definition and filling of them the programmer could access to different parts of the control functionality.

 

For a detailed documentation of all the methods, properties and events please consult the reference documentation.

Be aware that there is one set of documentation for both the VCL and ActiveX components.

 

Data Casting

 

One of the main problems when developing across different lenguages with cross-language libraries is how to map the data types; obviously,  all resources uses data types that could be found on all languages. But the documentation refers mostly to Pascal (Delphi 5) data types.

 

To make the translation take into consideration that the both the VCL and ActiveX components had been developed using just 3 different data types to simplify this issue:

 

• Integer, all numeric values are integers (long integer 32 bits).
• WideString, all alphanumeric information is stored on string types (far string pointer).
• WordBool, all logic values are stored into a word size boolean variables (32 bits).

 

Programming Tips & Techniques

 

 

Few initial topics from the programmer standpoint to be enriched as the components evolve and got actual feedback from programmers.

 

Approach

 

With the components you could approach the usage of AGW Packet Engine from at least three different perspectives:

 

1. Lw level.
2. Mid Level.
3. High Level.

 

The low level approach implies to use the components for little more than to actually skip the implementation of the TCP/IP socket and some connection details; you’ll gain little or nothing in terms of productivity and you have to deal with the complete knowledge of the AGW Packet Engine API. Basically you’ll use one method (AGWWrite) and one event (OnRead) with relevant properties. Still you’ll benefit a little from a consolidated API parser (all frames received by the application are already defragmented and validated as correct) and some relief on the connection/disconnection cycles of the API. In general requires a fair to good knowledge of the AGW Packet Engine API.

 

The mid-level approach requires that you need to know in general how the AGW Packet Engine interacts with an application but you could address the interaction from a higher level where many detailed tasks (such as sending queries and manage the asynchronous answer) are mostly solved. The main drawback of this approach is that you need to manage the connections by yourself. AGW Packet Engine carries all the connected information for all the connection held by all the registered callsigns thru the same channel and it’s on the application to differentiate the status of each connection.

 

The high level approach allows you to abstract on the details of how the AGW Packet Engine works and actually see the connections as little over an abstract implementation that you open, interact with and close thru handles (like files).

 

 

Go Raw

 

One particularly powerful feature of the AGW Packet Engine which is captured and supported by the components is the ability to work with raw frames (thru the SendRaw method and OnRaw event); there you could implement almost any application you could conceive using the AX.25 protocol. The price is complexity, when going that way you have to implement the full AX.25 protocol state machine.

The components provides some aids if you wish to go there anyway which are a value add against working with the Packet Engine alone (such as the capability to decode raw frames into fields and service functions).

 

 

Additional Objects

 

Almost any major program has to implement some sort of cyclic unconnected information delivery (UNPROTO) or to implement some sort of digipeater; those functions are simple (specially the beacon like unproto sender) but still you have to deal with timers, timeouts and the details of the ports.

 

The components allows to easily deploy both functionalities domain and to tailor them to your own needs thru the usage of event handlers in your own code; from a completely automated beacon where you set initially some properties and everything else is taken care to a complex unproto information delivery service.

 

A word of advice

 

Be aware that there are differences on the way the information is processed with low level functions (AGWWrite/OnRead) and the rest regarding the port numbering scheme.

 

For some reason George choose to use two different numbering conventions for the ports; one used by the AGW Packet Engine GUI (1..N) and another for the API (0..N-1).

 

The components uses the GUI convention (1..N).

 

Performance Considerations

 

It’s a fair statement to say that the components, albeit several “wrapper” layers are added” do really add too little in terms of footprint and overhead as opposed to develop the things by yourself straight. The ActiveX control is a little bulkier than the VCL component just because of the nature of ActiveX controls.

 

The key for performance is still to assign the events and activate the functions that you’re going ot use; there is no point to activate AGW Packet Engine to send all raw frames and then not implement the event handler because you don’t use them, the same with monitoring information. Both components allows a fair degree of control over which information is requested to the AGW Packet Engine and which not.

 

Keep your feets dry at all times, you could handle Terabytes of information by femptosecond on the memory of your machine, but all data eventually has to be received or sent thru radio ports that had limited bandwidth (and usually VERY limited bandwidth).

 

 

Support

 

Programmers should support programmers, beside some documentation that I had put together I plan to support the usage of the components mostly thru the Web and E-Mail resources.

 

Please refer to

 

http://www.qsl.net/lu7did/default.htm

 

For updates and documentation.

 

 

 

 

 

 

 

 

Known Bugs & Pending

 

·        Initial implementation, the underlying objects are well tested and prooven by the usage but the wrappers are brand new, don’t’ rule out bugs by the truckload; actual usage would tell. Feedback is important.

·        Documentation incomplete best that can do at this point.

·        The Rx/Tx counters on the AX.25 Link Manager has not been implemented yet.

·        Neither the VCL nor the ActiveX components bring an Icon on the desktop IDE when dragged and dropped; the VCL component shows an empty square and the ActiveX component a 0 X 0 icon (that could be enlarged for better view J).

 

 

 

Acknowledgements

 

Many people contributed with this program on its different development stages, I could not account for all of those that thru conversations (real, air or E-Mail) contributed to create in my mind the original idea.

 

The development itself wouldn’t be possible at all without George Rossopoulos (SV2AGW) providing the AGW Packet Engine (AGWPE) in the first place, extending the capability to interact with it thru TCP/IP as opposed to the somewhat arcane DDEML original interface the program had and lately reacting very promptly to make modifications and enhancements to AGWPE during the development and test stages.

 

 

I look forward for other people to actually use the program and provide positive or critic feedback of it just drop me a note with any special requirement or problem you might have.

 

 

Version Information

 

 

• Version 0.1 (Alpha)

Initial release. Basic functionality. Distributed for initial evaluation.

 

 

Disclaimer and License Statement

 

AGWAPI and AGWAPIx are free radioamateur and experimental uses, commercial use requires written permission from the author. The author bears no liability for damages related to the usage of this program nor guarantees the proper functional behaviour. I could certainly be more sophisticated in legal terms, but in a nutshell use it at your own risk.

Be aware that this is an alpha release more for evaluation and improvement than actual deployment.

Publicly available information has been used to understand the requirements, specially the AGWPE TCPIP Interface (AGWSockInterface.DOC by G.Rossopoulos SV2AGW) and the “AX.25 Amateur Packet Radio Link Layer Protocol” (AX25.DOC), all code used to implement this program comes from my own development.

The copyright of what you develop using the control belongs to the author, still no commercial distribution could be done of it without my written permission.

If you need support, have suggestions, encountered some bug or just are willing to provide feedback drop me a note at:

 

AX.25:   LU7DID@LU7DID.#ADR.BA.ARG.SOAM

Inet:    [email protected]