Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
Introduction
This document describes the design and specification of the AutoManager Document Server API (AMDSAPI).
The AutoManager API is meant to replace the current situation where ACADDSI inside AutoCAD is talking
directly to AutoManager WorkFlow and the AM-WorkFlow Document Server Interface. The goal of this API is
to enable other applications to access AM-WorkFlow functionality, and possibly to extend this functionality to
other Document Management Software, like AutoManager Organizer.
History:
Introduction................................................................................................................................................................
Design Goals...............................................................................................................................................................
Functions to be defined
Functions to be redefined or captured
Database Functions.....................................................................................................................................................
Profile Functions.........................................................................................................................................................
Redline Functions.......................................................................................................................................................
General Functions.......................................................................................................................................................
Setting up a link..........................................................................................................................................................
Function Descriptions.................................................................................................................................................
Error values
DsiEditCard
DsiGetField
DsiGetOpenFilename
DsiGetSaveFilename
DsiLockCard
DsiNewCard
DsiPutField
DsiQueryFilenameFromID
DsiQueryIDFromFilename
DsiReadGlobalProfile
DsiReadUserProfile
DsiRedCloseRedline
DsiRedNormalizeArc
DsiRedOpenRedline
DsiRedQueryNumLayers
DsiRedQueryLayerName
DsiRedReadEntity
DsiRedReStartRedline
DsiRedSetCurrentLayer
DsiRegisterApp
DsiUnregisterApp
DsiViewDocument
DsiWriteGlobalProfile
DsiWriteUserProfile
The second point can be specified more precisely with the following:
The CAD packages environment can be extended with functions to access document information that is
stored in the AutoManager database. This is similar to the getfield/putfield functions which are
available in the link with AutoCAD.
A titleblock link can be implemented. Information in the titleblock can be hot-linked with information in
the database, based on the getfield/putfield functions described above.
Redlines can be loaded or viewed in the current drawing, similar to the way this works in AutoCAD.
The CAD packages Open command can be extended in a way that the user can select a document with
help of AutoManager (using the Navigator, etc.). Other commands can also be extended in a similar
way.
If the development environment of the CAD package is powerful enough AutoManager could be notified
when a document is opened to synchronize document locking and to prevent locked documents to be
loaded (if possible).
Figure 1. The AutoManager Document Server API provides access to AutoManager WorkFlow functionality
from various applications.
In the desired situation the application (the CAD package) has little to do with AutoManager. All
communication should go through a clean API behind which the application specific calls are hidden. The
larger part of the locking and editing logic should be encapsulated in that API. Implementing this mechanism
as a separate DLL or executable has four advantages:
AM-WorkFlow needs little or no modification.
The actual AutoManager API is hidden from the application. AM-WorkFlow could be replaced by AM-
Organizer without the application being aware of it.
The application side of the link can be relatively thin compared to the current situation.
The application side needs only very basic calls to achieve the needed card locking and editing capabilities
currently available in ACADDSI.
Functions to be defined
Based on this API the application should provide a number of additional commands (if supported by the CAD
package):
AMWNEW Create a new drawing with a name provided by AM-WorkFlow. This will pop-up the
AM-WorkFlow user interface with a new card. AM-WorkFlow generates a filename.
AMWOPEN Open an existing drawing from the AM-WorkFlow database. This will pop-up AM-
WorkFlow and lets the user select a card.
AMWSAVE Save the current drawing.
AMWSAVEAS Save the current drawing under a new name.
AMWCLOSE Close the current drawing.
AMWXREF1 Attach another drawing from the AM-WorkFlow database as an external reference
to the current drawing. (AutoCAD specific)
AMWINSERT Insert another drawing from the AM-WorkFlow database in the current drawing as a
block. (AutoCAD specific)
AMWWBLOCK Save a block as a new document in the AM-WorkFlow database. (AutoCAD
specific)
AMWEDIT Let the user edit the titleblock. The dialog used in AutoCAD is shown in Figure 2.
Depending on the CAD packages capabilities this functionality can also be achieved
in a more user friendly manner by letting the user click the titleblock part he wants
to edit in the drawing and also let the editing be done in the drawing.
AMWOPTIONS Let the user set preferences. The configurable options depend on the application, but
in principle all of the options should be stored in the user profile (see Figure 4). The
most important option to the user is the option to redefine AutoCAD commands to
their AM-WorkFlow equivalent. For example, typing 'OPEN' would invoke
'AMWOPEN'. If the user selected 'Redefine using AM-WorkFlow', this would
directly go to AM-WorkFlow. If he selected 'Redefine using file browser', this would
first display a common Windows file browse dialog (see Figure 3).
AMWHELP Displays a simple dialog showing some help about the various commands. This is
the only help available, no help files are used (see Figure 5).
AMWVIEWRED Displays the redlines in the current drawing.
AMWHIDERED Hide the redlines again.
AMWUPDAT Transfers the information from the titleblock to AM-WorkFlow.
11
The XREF, INSERT and WBLOCK commands are specific to the AutoCAD environment. For other CAD packages similar
commands could be defined for their equivalents. These commands should display the same behavior to the user and perform the same function
as their original.
Figure 3. Dialog box to open a file, including a button to pass through to AM-WorkFlow.
Figure 5. The dialog showing very basic help for the various commands.
Also, if possible, a number of events should be trapped (regardless of the settings in AMWOPTIONS):
Opening of a file (locks a drawing).
Saving of a file (does not unlock a drawing, but might set a flag that the drawing is changed so that the
applications side knows that the card should be edited when the drawing is unlocked).
Saving of a file under a new name (unlocks the old drawing and creates and locks a new drawing).
Creation of a new document (creates and locks a new drawing).
Closing of a file (unlocks a drawing).
On these events locking and unlocking of the appropriate cards should be performed.
When a file is opened the application should call DsiQueryIDFromFilename to get the corresponding card ID.
If this fails the document is not yet in the database and should be added with a call to DsiNewCard with the
source card ID set to NULL. This should only be done if the user confirms that he wants to add the file.
When the document can be found in the database, it should be locked with a call to DsiLockCard. If this fails
the document is probably locked by some other application, and the application should at least notify the user
of this problem, but, if possible, close the file.
When the user closes the current file, the application should call DsiUnlockCard, and let the user edit the card
with DsiEditCard. This call lets the user interface of AM-WorkFlow pop up and go in edit mode.
To access the contents of the current card in the database, two functions are defined: DsiGetField and
DsiPutField. These are to be used to query the field contents to update the titleblock and vice versa.
User profiles
User profiles contain settings for the current user. Any configuration variables should be stored in this profile.
It is suggested that the application creates and uses a subsection of the section AMDSAPI , for example:
AMDSAPI.AutoCAD , AMDSAPI.Microstation or AMDSAPI.CadKey . Within its subsection the
application can store whatever data it needs to store. There are two functions defined for accessing user
profiles: DsiReadUserProfile and DsiWriteUserProfile.
Global profiles
The system profile contains settings for AutoManager. This can include global variables, also used by
BaseLisp. This system profile should be used with care, because this system profile contains the settings for all
users. The system profile is stored in a file that has the same name as the environment but with the extension
'.var'. There are two functions defined for accessing global profiles: DsiReadGlobalProfile and
DsiWriteGlobalProfile.
Note that most values such as integer and floating point values are stored in profiles as their ASCII
representations, but it is also possible to store binary data.
Entities
Entities are the basic building blocks of a redline. These entities can be grouped on different layers. Each entity
consists of a DSIENTITY structure which contains either a polyline or an arc. All coordinates that are passed
in this structure are in document coordinates.
Roles
A role is the part a user plays in the creation and maintenance of documents. The default roles include:
Supervisor, Manager, Editor, User and Viewer. These are the roles that are used in AMW. Each of these roles
has it's own access rights to the different layers. AMDSAPI handles all access rights with roles, so the
application side will not have to bother about them.
Layers
Layers group different entities belonging to a certain role, with specified access levels for other roles. The layer
name can be retrieved with the function DsiRedQueryLayerName and can be used to create a layer in the
drawing if needed..
Processing redlines
22
If the application was launched by AutoManager with the current document as an argument, AutoManager has not locked this
document yet. This is the responsibility of the application.
Error values
Syntax:
Arguments:
PTCHAR pszCardID
ID of the card to edit.
PTCHAR pszCaption
Caption to show in message box while waiting for AM-WorkFlow to finish.
PTCHAR pszMessage
Message to show while waiting for AM-WorkFlow to finish.
Returns:
USHORT
ERROR_ACCESS_DENIED
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_NOT_LOCKED
NO_ERROR
Description:
DsiEditCard notifies AM-WorkFlow to pop up and let the user edit the card. The card should be
locked by the current application. AM-WorkFlow pops up in edit mode, and when the user exits
edit mode, either by canceling or accepting changes, control is returned to the calling application
and AM-WorkFlow is pushed to the background. This behavior is achieved by using a BaseLisp
function (amdsapi-edit), defined in platf_w.lsp.
Syntax:
Arguments:
PTCHAR pszCardID
ID of the card to query.
PTCHAR pszField
Field to query.
PTCHAR pszValue
The buffer to receive the field contents.
USHORT usCnt
The size of the buffer, including terminating zero.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_FIELD
ERROR_INVALID_HANDLE
ERROR_NOT_FOUND
NO_ERROR
PTCHAR pszValue
Contains the contents of the field.
Description:
DsiGetField requests the contents of one specified field from the specified card. This card should
be locked by the current application.
Syntax:
Arguments:
PTCHAR pszFunction
String specifying the operation that is going to be performed with the filename that is
obtained. This string is used in the user interface, and can be somthing like 'openm', 'insert' or
'xref'.
PTCHAR pszCap
Caption of message box displayed while waiting for AM-WorkFlow to finish.
PTCHAR pszMsg
Message to display while waiting for AM-WorkFlow to finish.
BOOL fBrowse
TRUE: first a common file open dialog is presented, with a button to go to AM-
WorkFlow.
FALSE: go directly to AM-WorkFlow.
Returns:
USHORT
ERROR_ACCESS_DENIED
ERROR_BUSY_USERINTERFACE
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_GENERIC
ERROR_NO_CFG_LOADED
ERROR_NOT_LOGGED_IN
ERROR_OTHER_WLL_OPEN
NO_ERROR
Description:
Notifies AM-WorkFlow to pop up and let the user select a filename to open in the application.
AM-WorkFlow does not perform any additional actions: the card should be locked by the
application using DsiLockCard. In AM-WorkFlow the user can browse through the database using
the normal methods (navigator, selections etc.), and can either select a drawing to be opened in
the application or cancel back to the application through two extra menu entries: Open drawing
in <application name> and Cancel back to application name. The application name used is
the one specified with the call to DsiRegisterApp. This behavior is achieved with a BaseLisp
function (amdsapi-open), defined in platf_w.lsp.
Syntax:
Arguments:
PTCHAR pszCap
Caption of message box displayed while waiting for AM-WorkFlow to finish.
PTCHAR pszMsg
Message to display while waiting for AM-WorkFlow to finish.
BOOL fBrowse
TRUE: first a common file open dialog is presented, with a button to go to AM-
WorkFlow.
FALSE: go directly to AM-WorkFlow.
Returns:
USHORT
ERROR_ACCESS_DENIED
ERROR_BUSY_USERINTERFACE
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_NO_CFG_LOADED
ERROR_NOT_LOGGED_IN
ERROR_OTHER_WLL_OPEN
NO_ERROR
Description:
Pops up AM-WorkFlow or a file browser to get a new filename. AM-WorkFlow creates a new card
that the user can immediately edit, but does not perform any additional actions: the card should be
locked with the DsiLockCard call.
Syntax:
DsiLockCard(pszCardID, fLock)
Arguments:
PTCHAR pszCardID
ID of the card that should be locked or unlocked.
BOOL fLock
TRUE: the card will be locked.
FALSE: the card will be unlocked.
Returns:
USHORT
ERROR_ACCESS_DENIED
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_LOCKED
ERROR_NOT_LOCKED
NO_ERROR
Description:
Syntax:
Arguments:
PTCHAR pszCopyFrom
ID of the source card. If NULL or an empty string is passed, a new card will be created, using
defaults depending on the configuration used by AM-WorkFlow.
PTCHAR pszFilename
Filename to attach to the new card. If this string is empty a filename will be generated by AM-
WorkFlow.
USHORT usMaxLen
Length of the buffer to receive the generated filename. If a filename is specified in the call to
this API, this argument is ignored.
PTCHAR pszResult
Pointer to buffer to receive the ID for the created card.
USHORT usCnt
Length of the buffer to receive the new card ID.
Returns:
USHORT
ERROR_BAD_PATH_NAME
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
NO_ERROR
PTCHAR pszFilename
Contains the generated filename if there is no ID returned in pszResult.
PTCHAR pszResult
Contains the new card ID if there is no filename returned in pszFilename.
Description:
DsiNewCard lets AM-WorkFlow make a new card for the given filename and optionally copy the
contents of the specified card in it. If no filename is specified, a filename will be generated by
AM-WorkFlow and returned in the pszFilename argument 3. The original card does not need to be
locked, the new card will not be locked by this call.
3
AutoManager Organizer does not generate filenames automatically. In stead a file dialog will be shown.
Syntax:
Arguments:
PTCHAR pszCardID
ID of the card to modify.
PTCHAR pszField
Name of the field to modify.
PTCHAR pszValue
New contents for the field.
Returns:
USHORT
ERROR_ACCESS_DENIED
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_FIELD
ERROR_INVALID_HANDLE
ERROR_NOT_FOUND
ERROR_NOT_LOCKED
NO_ERROR
Description:
DsiPutField attempts to modify the contents for the specified field in the specified card. This card should be
locked by the current application. Some fields are not writeable by external applications. This is application
defined.
Syntax:
Arguments:
PTCHAR pszCardID
The ID of the card to get the filename for.
PTCHAR pszFileName
Buffer to receive the requested filename.
USHORT usCnt
Length of the buffer, including terminating zero.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_NOT_FOUND
NO_ERROR
PTCHAR pszFileName
Contains the requested filename, if found.
Description:
This call queries the filename for the given card ID from AM-WorkFlow. It is not necessary to
lock the card before this call. The requested filename is returned in the pszFileName.
Syntax:
Arguments:
PTCHAR pszFilename
Filename to get the ID for.
PTCHAR pszCardID
Buffer to receive the requested ID.
USHORT usCnt
Length of the buffer, including terminating zero.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_NOT_FOUND
NO_ERROR
PTCHAR pszCardID
Contains the requested ID, if found.
Description:
This call queries the ID for the given filename from AM-WorkFlow. It is not necessary to lock the
card before this call. The requested ID is returned in the pszCardID.
Syntax:
Arguments:
PTCHAR pszCardID
ID of the card to operate on.
PTCHAR pszSection
Section where key should be located.
PTCHAR pszKey
Key to read.
PTCHAR pszValue
Buffer to receive the value.
USHORT usCnt
The size of the buffer, including terminating zero.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
NO_ERROR
Description:
Reads the value for the given key in the given section from the user profile. The system profile
might be the same profile as the user profile, but for AM-WorkFlow this is the profile for the
current environment.
Syntax:
Arguments:
PTCHAR pszSection
Section where the key should be located.
PTCHAR pszKey
Key to read.
PTCHAR pszValue
Buffer to receive the value.
USHORT usCnt
Size of the buffer, including terminating zero.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
NO_ERROR
PTCHAR pszValue
Contains the value of the key.
Description:
Reads the value for the given key in the given section from the user profile. The user profile is
typically called <username>.ABU.
Syntax:
DsiRedCloseRedline()
Arguments:
Returns:
USHORT
NO_ERROR
Description:
Syntax:
DsiRedNormalizeArc(pArcNormal, pDsiEntity)
Arguments:
PARC_NORMAL pArcNormal
Pointer to structure that receives the normalized information on the arc.
PDSIENTITY pDsiEntity
Pointer to redline entity. This entity should be an arc.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
NO_ERROR
Description:
This API takes an arc entity, and calculates a different (more common) representation for it. This
information is returned in the structure of type ARC_NORMAL:
Syntax:
DsiRedOpenRedline(pszCardID)
Arguments:
PTCHAR pszCardID
ID of the card for which to open the redline profile.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
ERROR_RED_LOCKED
ERROR_RED_NO_REDLINES
ERROR_RED_UNKNOWN_USER
NO_ERROR
Description:
Checks if there are redlines for the specified card, and if so, opens the redline profile for this card
and reads the layer definitions. The profile should be closed with a call to DsiRedCloseProfile.
Syntax:
DsiRedQueryNumLayers(lpusNumRedlines)
Arguments:
LPUSHORT lpusNumRedlines
Points to a variable to receive the number of redline layers.
Returns:
USHORT
ERROR_INVALID_HANDLE
ERROR_RED_NOT_OPENED
NO_ERROR
LPUSHORT lpusNumRedlines
Contains the number of redline layers.
Description:
Queries the number of redline layers. This includes all layers, also those that the current user has
no access to.
Syntax:
Arguments:
PTCHAR pszLayerName
Pointer to buffer to receive the redline layer name.
USHORT usCnt
Size of buffer to receive the name of the layer, including terminating zero.
USHORT usLayerNum
Number of layer to get the name for.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_HANDLE
ERROR_RED_NOT_OPENED
NO_ERROR
PTCHAR pszLayerName
Buffer filled with the name for the specified layer.
Description:
This API queries the name for a layer. A layer name can include spaces and most all other
characters. The primary use for this function will be to provide a possible layer name to the CAD
package, if needed.
DsiRedReadEntity(ppDsiEnt)
Arguments:
Returns:
USHORT
NO_ERROR
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_RED_ALL_READY
ERROR_RED_BAD_ENTITY
ERROR_RED_LAYER_READY
ERROR_RED_NOT_OPENED
ERROR_RED_WRONG_USER
ppDsiEnt
Contains a pointer to the data the entity consists of, or NULL on error.
Description:
Reads the data for an entity on the current layer. After return ppDsiEnt points to a structure with
the following contents:
usEntType defines the type of the entity. All AM-WorkFlow redline entities (including text) are
reduced to the following simple type:
DSITYPE_POLYLINE is followed by a list of points that are to be connected.
DSITYPE_ARC is followed by three points on the arc. A circle is represented by two half
arcs, with both having three points.
dcEntColor contains the color for the entity in RGB values, using the following structure:
typedef struct _DSICOLOR
{
BYTE bRed;
BYTE bGreen;
BYTE bBlue;
} DSICOLOR, FAR * PDSICOLOR;
DsiRedReStartRedline()
Arguments:
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_HANDLE
ERROR_RED_NOT_OPENED
NO_ERROR
Description:
DsiRedSetCurrentLayer(usLayerNum)
Arguments:
USHORT usLayerNum
Number of the layer to set as current.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_HANDLE
ERROR_RED_BAD_LAYERNUM
ERROR_RED_NOT_OPENED
NO_ERROR
Description:
Sets the current layer to usLayerNum. The layer numbers start at 1, and the number of layers can
be queried with a call to DsiRedQueryNumLayers.
Syntax:
Arguments:
PTCHAR pszAppCode
Short code used by this application. This code is used internally in the AMDSAPI DLL.
Possible values: acad (AutoCAD), msdgn (Microstation), ckprt (CadKey) and gcgcd (Generic
CADD).
PTCHAR pszAppName
Descriptive name of the application, for example 'AutoCAD' or 'MicroStation'. For use in the
user interface, may not be NULL.
ULONG ulFlags
Flags describing capabilities or limitations of the applications. Currently defined:
DSIFLAG_MDI The application is capable of opening multiple files at the same
time.
HWND hwndApp
The handle for the main window of the application. This is used to move windows backward
and forward.
Returns:
USHORT
ERROR_APP_REFUSED
ERROR_INVALID_DATA
ERROR_NOT_ENOUGH_MEMORY
ERROR_NOT_LOGGED_IN
ERROR_START_APPLICATION
NO_ERROR
Description:
DsiRegisterApp registers it's name with the AMDSAPI DLL, which in turn checks with AM-
WorkFlow if this applications is allowed to use the AMDSAPI functions. This should be the first
action the application performs. Before termination of the application DsiUnregisterApp should be
called.
Syntax:
DsiUnregisterApp(VOID)
Arguments:
Returns:
USHORT
ERROR_INVALID_HANDLE
NO_ERROR
Description:
Removes the application from the list of registered applications. After this call no more AMDSAPI
calls are allowed. The supplied handle should be obtained with DsiRegisterApp. When cards are
locked by the application when this function is called, they are automatically unlocked. Although
the AMDSAPI DLL performs cleanup when it unloads - the DsiUnregisterApp function is called
for all registered applications - it is advised to call this function explicitly.
Syntax:
Arguments:
PTCHAR pszFilename
Name of document to view.
PTCHAR pszCaption
Caption of message to display while waiting for viewing to end.
PTCHAR pszMessage
Message to display while waiting for viewing to end.
Returns:
USHORT
ERROR_ACCESS_DENIED
ERROR_GENERIC
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
NO_ERROR
Description:
If the AM-WorkFlow user interface is not already busy in a dialog box this will pop up a viewer
window to view the specified document.
Syntax:
Arguments:
PTCHAR pszCardID
ID of the card to operate on.
PTCHAR pszSection
Section where the key should be located.
PTCHAR pszKey
The key to modify.
PTCHAR pszValue
Value to write to the key.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
NO_ERROR
Description:
Modifies the given key in the specified section of the system profile. The system profile might be
the same profile as the user profile, but for AM-WorkFlow this will be the profile containing the
current environment.
Syntax:
Arguments:
PTCHAR pszSection
Section in the user profile where the key should be changed/created.
PTCHAR pszKey
Key in the above section that should be changed.
PTCHAR pszValue
Value to change the key to.
Returns:
USHORT
ERROR_GENERIC
ERROR_INVALID_CARDID
ERROR_INVALID_DATA
ERROR_INVALID_HANDLE
ERROR_PROFILE_ACCESS
NO_ERROR
Description:
Changes the given key in the given section in the user profile to the specified value. If either
section or key or both do not exist, they are created. The user profile is typically called
<username>.ABU.