Scheduled Connections

The Connection Manager also enables you to configure an event (at a specific time) that will cause the device to wake up (if not already on), establish a connection to a network, and run an application. This can be particularly useful if you want a network operation to do something when the user is not around his or her device. Note that a scheduled event will remain registered until it has run or is deleted. In addition, an event remains scheduled across device reboots.

To set up a scheduled connection, you can use the ConnMgrRegisterScheduledConnection() function, which is defined as follows:

HRESULT WINAPI ConnMgrRegisterScheduledConnection(
   SCHEDULEDCONNECTIONINFO *pSCI);

The only parameter that is needed is a pointer to a SCHEDULEDCONNECTIONINFO structure:

typedef struct _SCHEDULEDCONNECTIONINFO {
   GUID guidDest;
   UINT64 uiStartTime;
   UINT64 uiEndTime;
   UINT64 uiPeriod;
   TCHAR szAppName[MAX_PATH];
   TCHAR szCmdLine[MAX_PATH];
   TCHAR szToken[32];
   BOOL bPiggyback;
} SCHEDULEDCONNECTIONINFO;

The guidDest member specifies the network identifier with which you want to create a connection. The next two members are used to set the start and end times for the connection. These should be set in the same format as the FILETIME structure, which specifies the amount of 100-nanosecond intervals since January 1, 1601.

The uiPeriod member is the amount of time (in 100-nanosecond units) between each connection attempt. If you set this to 0, the device will not wake up to make your connection.

The szAppName and szCmdLine members should point to the name of the application to run when the connection is made, and the command line that you want passed to the application, respectively.

The szToken member is a unique identifier that you can use to later delete the connection request.

Finally, the bPiggypack flag determines how the device should wake up for the event. If bPiggyback is set to TRUE, then the application specified by the szAppName parameter will execute as soon as the network connection to guidDest has been established. If it is set to FALSE, then the device will wake up only when another application or scheduled event connects to the same network.

The following code shows how you could schedule an application to run, 15 seconds from now. The scheduler will continue to attempt a connection every five minutes for the next hour:

// Get the network information where we want to establish a
// connection
GUID guidNetworkObject;
DWORD dwIndex = 0;
TCHAR tchRemoteUrl[256] = TEXT("\0");
wsprintf(tchRemoteUrl, TEXT("http://www.furrygoat.com/index.html"));

if(ConnMgrMapURL(tchRemoteUrl, &guidNetworkObject, &dwIndex)
        == E_FAIL) {
   OutputDebugString(TEXT("Could not map the request to a
        network identifier"));
   return FALSE;
}

// Get the time to launch
SYSTEMTIME sysTime;
FILETIME ftCurrent;
ULARGE_INTEGER ulCurrentTime;

GetLocalTime(&sysTime);
SystemTimeToFileTime(&sysTime, &ftCurrent);

ulCurrentTime.LowPart = ftCurrent.dwLowDateTime;
ulCurrentTime.HighPart = ftCurrent.dwHighDateTime;

// Set up the schedule times
// In 15 seconds, let's try every 5 minutes for an hour
DWORD dwSecStart = 15;
DWORD dwSecDuration = 3600;
DWORD dwSecPeriod = 300;

// Schedule a connection
SCHEDULEDCONNECTIONINFO sci;

memset(&sci, 0, sizeof(SCHEDULEDCONNECTIONINFO));
sci.uiStartTime =
   ulCurrentTime.QuadPart+(UINT64)(10*1000*1000)*dwSecStart;
sci.uiEndTime = ulCurrentTime.QuadPart+(UINT64)(10*1000*1000)*
                (dwSecStart+dwSecDuration);
sci.uiPeriod = (UINT64)(10*1000*1000)*(dwSecPeriod);
sci.guidDest = guidNetworkObject;
sci.bPiggyback = TRUE;

wsprintf(sci.szAppName, TEXT("\\Windows\\someapp.exe"));
wsprintf(sci.szCmdLine, TEXT("\\Windows\\someapp.exe"));
wsprintf(sci.szToken, TEXT("schdToken"));

HRESULT hr = ConnMgrRegisterScheduledConnection(&sci);

if(FAILED(hr)) {
   OutputDebugString(TEXT("Could not schedule the connection
      event"));
   return FALSE;
}

To delete a scheduled connection, you can call the following function:

HRESULT WINAPI ConnMgrUnregisterScheduledConnection(LPCTSTR
  pwszToken);

The only parameter that you need to send is the unique token that identifies the scheduled connection, as shown in the following example:

if(SUCCEEDED(ConnMgrUnregisterScheduledConnection(TEXT
       ("schdToken")))) {
   OutputDebugString(TEXT("Scheduled event has been
       cancelled."));
}