lightopc.h

OPCSERVER源代码

                   unsigned       tRight, /* OPC_READABLE|OPC_WRITEABLE */
                   VARIANT *tValue,  /* Canonical VARTYPE & default valid value */
                   double range_min,
                   double range_max);
/* A way to use EUtype OPC_ANALOG and don't be worried about SAFEARRAYs */

LO_PUBLIC
int loAddRealTag_b(loService *, /* actual service context */
                   loTagId       *ti, /* returned TagId */
                   loRealTag      rt,
                   const char    *tName,
                   int            tFlag, /* loTF_XXX */
                   unsigned       tRight, /* OPC_READABLE|OPC_WRITEABLE */
                   loTagId        tBase);
/* Use the default tValue & type and EUinfo of an existing tag tBase.
   It saves some memory for groups of similar tags. */

LO_PUBLIC
int loAddRealTagW(loService *,
                  loTagId       *ti,
                  loRealTag      rt,
                  const loWchar *tName,
                  int            tFlag, /* loTF_XXX */
                  unsigned       tRight, /* OPC_READABLE|OPC_WRITEABLE */
                  VARIANT *tValue,
                  /*OPCEUTYPE*/int tEUtype,
                  VARIANT *tEUinfo);

LO_PUBLIC
int loAddRealTag_aW(loService *,
                    loTagId       *ti,
                    loRealTag      rt,
                    const loWchar *tName,
                    int            tFlag, /* loTF_XXX */
                    unsigned       tRight, /* OPC_READABLE|OPC_WRITEABLE */
                    VARIANT       *tValue,
                    double range_min,
                    double range_max);

LO_PUBLIC
int loAddRealTag_bW(loService *, /* actual service context */
                    loTagId       *ti, /* returned TagId */
                    loRealTag      rt, /* != 0 */
                    const loWchar *tName,
                    int            tFlag, /* loTF_XXX */
                    unsigned       tRight, /* OPC_READABLE|OPC_WRITEABLE */
                    loTagId        tBase);
/* Use the default tValue & type and EUinfo of an existing tag tBase.
   It saves some memory for groups of similar tags. */

LO_PUBLIC
loTrid loCacheUpdate(loService *, unsigned count, loTagValue taglist[], FILETIME *timestamp);
 /* Put the new tags values into server cache. Server will expose
  cached tags to the OPC-clients. This function doesn't write in
  cache immediately but queued request to update cache thus it isn't
  a time-spending routine.
  The tvState.tsTime is have to be set too.
  The timestamp is dedicated to interrupt-driven tags.
  If a tag have tvState.tsTime = 0 then the timestamp from latest completed
  transaction will be reported to clients for this tag. loUpdateCache() will
  update this global timestamp even if count is 0.
  A null pointer doesn't change the last cpecified timestamp.
  Returns 0 on an error or transaction id for this update */

#define loCH_TIMESTAMP (~0)

LO_PUBLIC
loTagValue *loCacheLock(loService *);
LO_PUBLIC
loTrid loCacheUnlock(loService *, FILETIME *timestamp);
/* The alternative way to update the secondary cache.
   A valid loTagId can be used as index in the returned array.
   NOTE: All fields of an updated loTagValue should be set,
   including tvTi and tvState.tsTime. But on the other hand the LightOPC
   will never change tvState.tsError nor tvState.tsQuality.
   VARIANTS should be copied using VariantCopy().

   It will be better if driver will preserve original canonical datatype
   as specified in loAddRealTag().

   If the tvTi field is set to loCH_TIMESTAMP the only timestamp will be
   updated. Be ware the previous update transaction may be not copleted yet.
   In this case tvTi contains non-zero value and you may not change it to
   loCH_TIMESTAMP. Althrough you're free to update the timestamp only or
   the whole loTagValue.

   Anoter way to use the interrupt driven tags is to specify timestamp.
   In this case all tags with zero timestamps (even not touched in the current
   update transaction) will be reported with the specified timestamp.
   A null pointer doesn't change the last cpecified timestamp. */

/* NOTE: These cache-update functions are especially designed to
   never cause unpredictable delays. Thus they can be safely used
   nside hardware polling loops. */

LO_PUBLIC
int loCacheTimestamp(loService *se, unsigned count, const FILETIME ts[]);

/* Update the timestamp array (ts[count]).

   This function can be called safely only in the middle of 
   loCacheLock() - loCacheUnlock().

   If count is greater than a previous count then array will be enlarged.
   The ENOMEM error is possible in this case.

   NOTE: if a tag has (tsTime.dwHighDateTime == 0) then 
   tsTime.dwLowDateTime will be used as index in the timestamp array.
   Time from timestamp array will be substituted when data is will be 
   sent to client. 
   NOTE: The first item of ts[0] must have a non-zero dwHighDateTime!

   The loCacheUpdate() and loCacheUnlock() modify the first [0] entry 
   of this array.
*/

LO_PUBLIC
HRESULT loEnumStrInsert(LPENUMSTRING, const loWchar *);
   /* Adds string to enumerator passed to ldBrowseAccessPath().
   This function should not be used on another enums! */

LO_PUBLIC
const char *loClientName(loClient *); /* return client-defined name, useful for
   debugging. Returned name may changes at any momoment but it still valid
   nul-terminated string until client released. This function must be called for
   an unreleased client
   only, or for client passed to a driver callback from inside this callback. */

#define loOP_OPERATE    (1)
#define loOP_STOP       (2)
#define loOP_SHUTDOWN   (4)
#define loOP_DISCONNECT (8)
#define loOP_DESTROY   (16)

LO_PUBLIC
int loSetStateW(loService *se, loClient *cli, int oper, int state, const loWchar *reason);
LO_PUBLIC
int loSetState(loService *se, loClient *cli, int oper, int state, const char *reason);
/* Set status for specified client or for all clients if cli=0.
   oper is operating mode - any combination of loOP_XXXXX or 0 - keep unchanged;
   state is from OPCSERVERSTATE or 0 - keep unchanged.
   reason will be reported for client on shutdown; 0 - keep unchanged.

   Use loOP_OPERATE to turn server on after a loOP_STOP.

   In case of loOP_STOP almost all server's functions will
   return an error to client, so server probably will be released by client.

   The loOP_SHUTDOWN cause sending IOPCShutdown callback to client.
   Since loOP_SHUTDOWN is passed the server may not be turned to loOP_OPERATE.

   loOP_DISCONNECT forces CoDisconnetObject() for the client and all groups,
   and for enumerators returned by the server.

   Usual sequence of graceful shutdown: loOP_SHUTDOWN-loOP_STOP-loOP_DISCONNECT,
   though loServiceDestroy() does the same except waitings between changes in state.

   loOP_DESTROY cause unconditional (though a bit delayed) destruction of loClient.
   It is unsafe to use loOP_DESTROY for in-proc servers, or when loOP_DISCONNECT and
   loOP_STOP have not been set.

   Returns: EINVAL on bad state;
            ENOENT on bad cli;
            EBADF  on bad se.
*/

LO_PUBLIC
int loGetBandwidth(loService *se, loClient *cli);
/* Returns current OPCSERVERSTATUS::Bandwidth for specified client.
   Or the worst bandwidth if cli == 0.
   Or -1 if se or cli is invalid. */

LO_PUBLIC
loTrid loTridLast(loService *);   /* get the last id of primary cache update. */
LO_PUBLIC
int loTridWait(loService *, loTrid); /* wait for data be moved to primary cache. */
/* returns -1 when an invalid trid is specified, 1 when wait is comleted */
/* both functions returns 0 when service is about to stopping */
/* A driver usally don't have to use these functions. */
LO_PUBLIC
int loTridOrder(loTrid earlier, loTrid latter);
/* Compare two loTrid and return a non-zero value
   if the earlier is equal to or really earlier than the latter.
   For example
              loOrderedTrid(my_trid, loTridLast(my_service))
   will return 1 when my_trid is already committed to primary cache. */

/****************************************************************************
 Custom Properties:
*/

LO_PUBLIC
loPLid loPropListCreate(loService *se);
/* Create an empty Properties' List.
   Zero value returned in case of insufficient memory or invalid loService. */

#define loPROPLIST_MAX (3)

LO_PUBLIC
int loPropListAssign(loService *se, loPLid plid, loTagId ti, int prio);
/*
  Assign the PropertyList plid to the specified tag ti.
  A PropList may be assigned to several tags.
  Each Tag may carry up to loPROPLIST_MAX property lists,
  identified by <prio>.

  A property searched through all lists from 1 (highest priority) to
  loPROPLIST_MAX (lowest priority) then "six special" properies will be checked.

  zero plid makes appropriating <prio> list empty.

  Returns 0 if Ok.
*/

LO_PUBLIC
int loPropertyAdd(loService *se, loPLid plid, unsigned propid,
                  VARIANT *val, const char *path, const char *description);
LO_PUBLIC
int loPropertyAddW(loService *se, loPLid plid, unsigned propid,
                  VARIANT *val, const loWchar *path, const loWchar *description);
 /* Add the property to the PropertyList.

    <path> is optional (can be NULL) - it used for LookupItemIDs().
    <description> is optional (can be NULL) - it is desirable for non-standard
       properties.
 *! BE WARE! unlike other parameters the <description> will *NOT* be duplicated
 *! by LightOPC. The <description> pointer will be stored "as is" instead.
 *! Therefore you have to make the passed string persistent until this
 *! property removed from list or loService destroyed.

 if the <path> begins from loDriver::ldBranchSep it treated as relative to
 appropriate ItemId.
 For example, prperty list assigned to tag named  "device/port/one"

    path:    LookupItemIDs() will return:
             for "device/port/one"     for "device/port/"  for "device//"

1)    "/Two"   "device/port/one/Two"     "device/port/Two"   "device/Two"
2)   "//Two"   "device/port/Two"         "device/port/Two"   "device/Two"
3)  "///Two"   "device/Two"              "device/Two"        "device/Two"
4) "////Two"   "Two"                     "Two"               "Two"
5)     "Two"   "Two"                     "Two"               "Two"
6)       "/"   "device/port/one"         "device/port"       "device"
7)      "//"   "device/port"             "device/port"       "device"
8)     "///"   "device"                  "device"            "device"
9)    "////"   ""    *invalid*           ""                  ""

  Return value: 0 if successfull
          EEXIST  the list already contains such propid.

  NOTE: Using of trailing branch separators in tags' names (as in "device//")
  allows you to assign the same PropertyList to a "upper" branch as well as
  to "lower" leafs. See lines (2) and (3). In other aspects such trailing
  separators will be stripped out.
*/

LO_PUBLIC
int loPropertyChange(loService *se, loPLid plid, unsigned propid, VARIANT *val);
/* Change the value of a property in the list */

LO_PUBLIC
int loPropertyRemove(loService *se, loPLid plid, unsigned propid);
/* Remove the property from list */


/*****************************************************************************/

/* Set integration time (in milliseconds) for bandwidth caclulations.
   Must be in range 16...10000.
   May cause abnormal bandwidth reported for a short time. */
LO_PUBLIC
unsigned lo_statperiod(unsigned); /* internal */

/* Converting Variant VT_DATE to/from FILETIME.
   Precision is about +-1 us, probably better than SystemTimeToVariantTime() 
   see hr_clock.c for details */
LO_PUBLIC
double lo_filetime_to_variant(const FILETIME *ft);
LO_PUBLIC
void   lo_variant_to_filetime(FILETIME *ft, double vd);

/* Converting Variant+VT_ARRAY */
LO_PUBLIC
HRESULT lo_variant_changetype_array(VARIANT *dst, VARIANT *src, 
                                    LCID lcid, unsigned short flags, 
                                    VARTYPE vt);


#ifdef __cplusplus
	}
#endif

/*********************  end of lightopc.h *********************************/

#endif /* LIGHTOPC_H */