Lock

eLockType

[in] The desired IoLockType for the session.

lLockTimeout

[in] The amount of time (in milliseconds) to wait for the lock.

strRequestedKey

[in] The requested key to use when requesting a shared lock. Not applicable when eLockType is IoLockExclusive.

strAccessKey

[out] The access key returned by the I/O session. Not applicable when eLockType is IoLockExclusive.

Returns S_OK if successful, otherwise a failure HRESULT.

This function is used to obtain a lock on the device I/O session. The caller can specify the type of lock requested and the length of time the operation will suspend while waiting to acquire the lock before timing out.

The strRequestedKey and the strAccessKey parameters apply only to shared locks. These parameters are not applicable when the access mode is IoLockExclusive. The I/O session allows user applications to specify a key to be used for lock sharing, through the use of the requestedKey parameter. Alternatively, a you can pass an empty string for the strRequestedKey parameter when obtaining a shared lock, in which case a unique access key will be generated and returned in the strAccessKey parameter. If a user application does specify a strRequestedKey value, the I/O session will try to use this value for the strAccessKey. As long as the resource is not locked, the strRequestedKey will be used as the access key and the lock will be granted.

The following example demonstrates use of the Lock function to obtain an exclusive lock. The example shows of the Printf and Scanf functions to retrieve the *IDN? response string from the device. A lock is used to ensure that no other thread or process attempts to access the device between the Printf and Scanf calls.

// CoAcme4321.cpp
HRESULT Acme4321::Configure()
{
  HRESULT hr = S_OK;

  // Request an exclusive lock to block other sessions from interrupting the *IDN query
  hr = io.Lock(IoLockExclusive, 2000, _T(""), _T(""));
  if (SUCCEEDED(hr))
  {
    hr = io.Printf(_T("*IDN?"));
    if (SUCCEEDED(hr))
    {
      CString strId;
      hr = io.Scanf(_T("%$Cs"), strId);
    }

    // Unlock the session so other threads and processes can use it
    HRESULT hr2 = io.Unlock();
    hr = FAILED(hr) ? hr : hr2;
  }

  return hr;
}

The following example demonstrates use of the Lock function to obtain a shared lock with an access key. Other I/O sessions can use this access key in the requestedKey parameter of the Lock function to share access to the locked device.

The example then shows the original session acquiring an exclusive lock while maintaining its shared lock. When the session holding the exclusive lock unlocks the resource via the Unlock function, all sessions sharing the lock will again have the access privileges associated with the shared lock..

// CoAcme4321.cpp
HRESULT Acme4321::Configure()
{
  HRESULT hr = S_OK;

  // Request a shared lock so that only processes we "know" about can access the device
  CString strAccessKey;
  hr = io.Lock(IoLockShared, 2000, _T(""), strAccessKey);
  if (SUCCEEDED(hr))
  {
    // At this point, we "publish" the value of strAccessKey to other processes
    // to which we want to grant access privileges.  This can be done using
    // any desired interprocess communication mechanism

    hr = io.Printf(_T("*RST?;SENS:CONFIG DEF"));
    if (SUCCEEDED(hr))
    {
      // Now lock out all other threads (including those that share the key)
      // so that the *IDN? query doesn't get interrupted
      hr = io.Lock(IoLockExclusive, 2000, _T(""), _T(""));
      if (SUCCEEDED(hr))
      {
        hr = io.Printf(_T("*IDN?"));
        if (SUCCEEDED(hr))
        {
          CString strId;
          hr = io.Scanf(_T("%$Cs"), strId);
        }

        // Release the exclusive lock
        HRESULT hr2 = io.Unlock();
        hr = FAILED(hr) ? hr : hr2;
      }

      // Release the shared lock
      HRESULT hr2 = io.Unlock();
      hr = FAILED(hr) ? hr : hr2;
    }
  }

  return hr;
}

Other Resources