home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1999 January / pcwk_01_1999.iso / Wtestowe / Vistdstd / Install / Data.Z / VAO.C < prev    next >
C/C++ Source or Header  |  1996-08-13  |  9KB  |  281 lines
  1. /*    VAO.C - Fundamental routines needed to implement a VSL for Visio.
  2.  *  Copyright (C) 1991-1996 Visio Corporation. All rights reserved.
  3.  *
  4.  *    This file provides implementations for the routines prototyped
  5.  *    in vao.h.
  6.  *
  7.  *    Vao.h defines the interface between Visio and VSLs. A VSL is a 
  8.  *    dynamic link library that implements the protocol defined in vao.h. 
  9.  *    A VSL implements one or more Visio Add-ons. 
  10.  *
  11.  *    The c-cpp directory shipped with Visio contains this vao.c file and
  12.  *    vao.h. It also contains the source files for a sample VSL written in 
  13.  *    C and a sample VSL written in C++. Both projects include this vao.c
  14.  *    file. The source for the sample projects is portable to either WIN16 
  15.  *    or WIN32, but there are separate .mak files provided for building the 
  16.  *    WIN16 or WIN32 versions.
  17.  *
  18.  *    If you're developing a VSL, you can opt to use the implementations 
  19.  *    provided by this vao.c file. But you're not required to use them.
  20.  *    So long as your VSL implements the protocol defined in vao.h, you
  21.  *    can implement it however works best for you.
  22.  */
  23.  
  24. #include "vao.h"
  25.  
  26. //---------------------------------------------------------------------------
  27. //    *** GLOBAL (TO THIS DLL) DATA DEFINED IN THIS FILE ***
  28. //---------------------------------------------------------------------------
  29.  
  30. // Gbl_hDLLModule is the instance handle for the dll this code is running in.
  31. // It gets set in LibMain() when this dll gets loaded. VLIBUTL_hModule()
  32. // simply returns gbl_hDLLModule to its callers.
  33.  
  34. HINSTANCE gbl_hDLLModule = NULL;
  35.  
  36. //---------------------------------------------------------------------------
  37. //    PRIVATE: VAO DATA STRUCTURES AND STATIC DATA
  38. //---------------------------------------------------------------------------
  39.  
  40. // Stc_VisioCallBack simply stores the address of the entry point in
  41. // Visio that the lib is to call when it wants to call Visio back. This
  42. // address is passed to the lib (amongst other times) when Visio sends
  43. // a load message to the lib. Stc_VisioCallBack is initialized by
  44. // VAOUtil_SetVisCallBack(). VAOUtil_VisCallBack() returns its value.
  45. //
  46. // VAOUtil_SetVisCallBack() is called by VAOUtil_DefVisMainProc() when it
  47. // handles a load message from Visio.
  48. //
  49. // Thus if a VSL calls VAOUtil_DefVisMainProc() when Visio sends a load 
  50. // message to it, it need never call VAOUtil_SetVisCallBack().
  51. //
  52. // However, if it opts not to use VAOUtil_DefVisMainProc() to handle load
  53. // messages, and if it wants to use one of the several utilities defined
  54. // herein that depend on stc_VisioCallBack, then the lib should call
  55. // VAOUtil_SetVisCallBack() when it handles a load message from Visio.
  56. //
  57. static LPVAOFUNC stc_VisioCallBack = (LPVAOFUNC)NULL;
  58.  
  59. //---------------------------------------------------------------------------
  60. //    IMPLEMENTATION OF BASIC SERVICES FOR ADD-ONS:
  61. //---------------------------------------------------------------------------
  62.  
  63. #ifdef __BORLANDC__
  64. #pragma argsused
  65. #endif
  66. VAOU_PROC(VAORC) VAOUtil_DefVisMainProc ( VAOMSG    wMsg,
  67.                                           WORD        wParam,
  68.                                           LPVOID    lpParam,
  69.                                           HINSTANCE    hResources )
  70.     {
  71.     // Provides default response to messages from Visio.
  72.     //
  73.     // If you're familiar with DefWindowProc() in Windows, this is the analog
  74.     // for use in Visio Add-ons. Just like you use DefWindowProc() from a
  75.     // window procedure to handle a window message that you don't want to
  76.     // implement specific behavior for, you can use VAOUtil_DefVisMainProc()
  77.     // from your Add-on's VisioLibMain() to handle messages from Visio that
  78.     // you don't want to implement specific behavior for.
  79.     //
  80.     // VAOUtil_DefVisMainProc()'s prototype ALMOST matches that of
  81.     // VisioLibMain().
  82.     //
  83.     // If your VisioLibMain() is called and you don't want to handle the
  84.     // message, then just call VAOUtil_DefVisMainProc() with the arguments
  85.     // passed to VisioLibMain() and return whatever it returns.
  86.     // VAOUtil_DefVisMainProc()'s responses will be correct, albeit not
  87.     // particularly interesting.
  88.     //
  89.     // VAOUtil_DefVisMainProc()'s prototype differs from VisioLibMain()'s in
  90.     // that it has an extra parameter, namely hResources. This should always
  91.     // be passed as null.
  92.     //
  93.     #define lpv2lparm ((LPVAOV2LSTRUCT)lpParam)
  94.  
  95.     VAORC result = VAORC_SUCCESS;
  96.  
  97.     switch ( wMsg )
  98.         {
  99.         case V2LMSG_LOAD:
  100.             //
  101.             // wParam:    Interface version being used by sending Visio.
  102.             // lpParam: LPVAOFUNC (Address of Visio's call back proc.)
  103.             //
  104.             // proper response: VAO_L2V_VERSION() | VAORC_L2V_LOADFAILED
  105.             //
  106.             result = VAO_L2V_VERSION();
  107.  
  108.             // We stash call back address for later use by these utilities.
  109.             //
  110.             // If this is first load, we expect VAOUtil_VisCallBack() to
  111.             // be null, otherwise we've been loaded before and we expect
  112.             // lpParam to equal existing call back address or we're talking
  113.             // to different vaomgr's with different call back addresses which
  114.             // this design can't handle.
  115.             //
  116.             if ( !VAOUtil_VisCallBack() )
  117.                 VAOUtil_SetVisCallBack((LPVAOFUNC)lpParam);
  118.  
  119.             else if ( VAOUtil_VisCallBack() != (LPVAOFUNC)lpParam )
  120.                 result = VAORC_L2V_LOADFAILED;
  121.  
  122.             break;
  123.  
  124.         case V2LMSG_UNLOAD:
  125.             //
  126.             // wParam:    undefined
  127.             // lpParam: null
  128.             //
  129.             // proper response: moot (but VAORC_SUCCESS is appreciated)
  130.             //
  131.             break;
  132.  
  133.         case V2LMSG_ENUMADDONS:
  134.             break;
  135.  
  136.         case V2LMSG_ISAOENABLED:
  137.             //
  138.             // wParam:    Ordinal of Add-on to determine enabled status of.
  139.             // lpParam: LPVAOV2LSTRUCT
  140.             //
  141.             // proper response: VAORC_L2V_ENABLED | 0
  142.  
  143.             result = VAORC_L2V_ENABLED;
  144.             break;
  145.  
  146.         case V2LMSG_RUN:
  147.             //
  148.             // wParam:    Ordinal of Add-on to run.
  149.             // lpParam: LPVAOV2LSTRUCT
  150.             //
  151.             // proper response: VAORC_SUCCESS |
  152.             //                    VAORC_L2V_MODELESS |
  153.             //                    VAORC_error
  154.             break;
  155.  
  156.         case V2LMSG_RUNABOUT:
  157.             //
  158.             // wParam:    Ordinal of Add-on to run.
  159.             // lpParam: LPVAOV2LSTRUCT
  160.             //
  161.             // proper response: VAORC_SUCCESS |
  162.             //                    VAORC_L2V_MODELESS |
  163.             //                    VAORC_error
  164.             break;
  165.  
  166.         case V2LMSG_RUNHELP:
  167.             //
  168.             // wParam:    Ordinal of Add-on to run.
  169.             // lpParam: LPVAOV2LSTRUCT
  170.             //
  171.             // proper response: VAORC_SUCCESS |
  172.             //                    VAORC_L2V_MODELESS |
  173.             //                    VAORC_error
  174.             break;
  175.  
  176.         case V2LMSG_KILLSESSION:
  177.             {
  178.             // wParam:    0
  179.             // lpParam: LPVAOV2LSTRUCT
  180.             //
  181.             // proper response: moot
  182.             //
  183.             break;
  184.             }
  185.  
  186.         default:
  187.             result = VAORC_L2V_BADMSG;
  188.             break;
  189.         };
  190.  
  191.     return result;
  192.     }
  193.  
  194.  
  195. VAOU_PROC(VOID) VAOUtil_SetVisCallBack ( LPVAOFUNC lpfunc )
  196.     {
  197.     // VAOUtil_SetVisCall() is to be called in order to tell these utilities
  198.     // Visio's call back address. VAOUtil_SetVisCallBack() typically need
  199.     // not be called by an Add-on library.
  200.     //
  201.     stc_VisioCallBack = lpfunc;
  202.     }
  203.  
  204.  
  205. VAOU_PROC(LPVAOFUNC) VAOUtil_VisCallBack ( )
  206.     {
  207.     // VAOUtil_VisCallBack() simply returns the address of Visio's call
  208.     // back procedure.
  209.     //
  210.     return stc_VisioCallBack;
  211.     }
  212.  
  213.  
  214. #if !defined(_WIN32)
  215. VAOU_PROC(HINSTANCE) VAOUtil_hAppInst ( )
  216.     {
  217.     // This returns the instance handle of the currently running exe that
  218.     // has called the dll into which VAOUtil_hAppInst() is linked (which is
  219.     // presumably an instance of Visio).
  220.     //
  221.     // Note that you can ascertain the running instance handle via fashions
  222.     // other than by calling VAOUtil_hAppInst().
  223.     //
  224.     // In particular, if you were willing to allow your lib to depend on
  225.     // toolhelp.lib, then the actual implementation done here is in effect
  226.     // equivelent to, albeit more slimy than:
  227.     //
  228.     //        #include <toolhelp.h>
  229.     //        HINSTANCE result = (HINSTANCE)NULL;
  230.     //        HTASK hCurTask;
  231.     //        if ( (hCurTask = GetCurrentTask()) )
  232.     //            {
  233.     //            TASKENTRY te;
  234.     //            te.dwSize = sizeof(te);
  235.     //            if ( TaskFindHandle((TASKENTRY FAR*)&te,hCurTask) )
  236.     //                result = te.hInst;
  237.     //            }
  238.     //        return result;
  239.  
  240.     // -- See MSWindows SDK Programmer's Ref. Vol. 3 pp. 407
  241.     // -- See Undocumented Windows pp. 194
  242.  
  243.     return (HINSTANCE)
  244.                 *((LPWORD)( (((DWORD)(WORD)GetCurrentTask()) << 16 ) |
  245.                             0x1C ));
  246.     }
  247. #endif /* !defined(_WIN32) */
  248.  
  249.  
  250. VAOU_PROC(VAORC) VAOUtil_RegisterAddons ( WORD                wSessID,
  251.                                           LPVAOREGSTRUCT    lpRegStructArray,
  252.                                           WORD                nRegStructs )
  253.     {
  254.     // This registers Add-ons with Visio for a lib.
  255.     //
  256.     // This simply takes a pointer to a contiguous array of filled out Visio
  257.     // Add-on registration structures (see vao.h) with nRegStructs
  258.     // entries and registers the described Add-ons with Visio. Typically
  259.     // Add-ons are registered in response to an enumAddOns message that Visio
  260.     // has sent to the lib. WSessID should be the session id passed to the
  261.     // lib along with the enumAddOns message.
  262.  
  263.     VAORC result = VAORC_SUCCESS;
  264.  
  265.     if ( lpRegStructArray )
  266.         {
  267.         for ( ;
  268.               result == VAORC_SUCCESS && nRegStructs;
  269.               nRegStructs--, lpRegStructArray++ )
  270.             {
  271.             result = ((*stc_VisioCallBack)(L2VMSG_REGADDON,
  272.                                            wSessID,
  273.                                            lpRegStructArray));
  274.             }
  275.         }
  276.     else
  277.         result = VAORC_FAILURE;
  278.  
  279.     return result;
  280.     }
  281.