Creating a Source Initiated Subscription
Source-initiated subscriptions allow you to define a subscription on an event collector computer without defining the event source computers, and then multiple remote event source computers can be set up (using a group policy setting) to forward events to the event collector computer. Before a local computer can subscribe to events and a remote computer can forward events, both computers must be set up for event collecting and event forwarding. For more information about how to configure the computers, see Setting up a Source Initiated Subscription.
The following code example follows a series of steps to create a source initiated subscription where the event sources are in the same domain as the event collector computer.
To programmatically create a source-initiated subscription
- Open the subscription by providing the subscription name and access rights as parameters to the EcOpenSubscription function. For more information about access rights, see Windows Event Collector Constants.
- Set the properties of the subscription by calling the EcSetSubscriptionProperty function. For more information about subscription properties that can be set, see the EC_SUBSCRIPTION_PROPERTY_ID enumeration.
- Save the subscription by calling the EcSaveSubscription function.
- Close the subscription by calling the EcClose function.
The following C++ example shows how to create a source initiated subscription:
#include <windows.h>
#include <iostream>
using namespace std;
#include <string>
#include <xstring>
#include <conio.h>
#include <EvColl.h>
#include <vector>
#include <wincred.h>
#pragma comment(lib, "credui.lib")
#pragma comment(lib, "wecapi.lib")
// Track properties of the Subscription.
typedef struct _SUBSCRIPTION_SOURCE_INITIATED
{
std::wstring Name;
EC_SUBSCRIPTION_TYPE SubscriptionType;
std::wstring Description;
BOOL SubscriptionStatus;
std::wstring URI;
EC_SUBSCRIPTION_CONFIGURATION_MODE ConfigMode;
EC_SUBSCRIPTION_DELIVERY_MODE DeliveryMode;
DWORD MaxItems;
DWORD MaxLatencyTime;
DWORD HeartbeatInerval;
time_t Expires;
std::wstring Query;
BOOL ReadExistingEvents;
std::wstring TransportName;
EC_SUBSCRIPTION_CONTENT_FORMAT ContentFormat;
std::wstring DestinationLog;
std::wstring AllowedSourceNonDomainComputers;
std::wstring AllowedSourceDomainComputers;
} SUBSCRIPTION_SOURCE_INITIATED;
// Subscription Information
DWORD GetProperty(EC_HANDLE hSubscription,
EC_SUBSCRIPTION_PROPERTY_ID propID,
DWORD flags,
std::vector<BYTE>& buffer,
PEC_VARIANT& vProperty);
void __cdecl wmain()
{
LPVOID lpwszBuffer;
DWORD dwRetVal = ERROR_SUCCESS;
EC_HANDLE hSubscription;
EC_VARIANT vPropertyValue;
std::vector<BYTE> buffer;
PEC_VARIANT vProperty = NULL;
SUBSCRIPTION_SOURCE_INITIATED sub;
sub.Name = L"TestSubscription-SourceInitiated";
sub.SubscriptionType = EcSubscriptionTypeSourceInitiated;
sub.Description = L"A subscription that collects events that are published in\n" \
L"the Microsoft-Windows-TaskScheduler/Operational log and forwards them \n" \
L"to the ForwardedEvents log.";
sub.URI = L"http://schemas.microsoft.com/wbem/wsman/1/windows/EventLog";
sub.Query = L"<QueryList>" \
L"<Query Path=\"Microsoft-Windows-TaskScheduler/Operational\">" \
L"<Select>*</Select>" \
L"</Query>" \
L"</QueryList>";
sub.DestinationLog = L"ForwardedEvents";
sub.ConfigMode = EcConfigurationModeCustom;
sub.MaxItems = 5;
sub.MaxLatencyTime = 1000;
sub.HeartbeatInerval = 60000;
sub.DeliveryMode = EcDeliveryModePush;
sub.ContentFormat = EcContentFormatRenderedText;
sub.ReadExistingEvents = true;
sub.SubscriptionStatus = true;
sub.TransportName = L"http";
// This SDDL grants members of the Domain Computers domain group as well
// as members of the Network Service group (for the local forwarder),
// the ability to raise events for this subscription.
sub.AllowedSourceDomainComputers = L"O:NSG:NSD:(A;;GA;;;DC)(A;;GA;;;NS)";
// Step 1: Open the Event Collector subscription.
hSubscription = EcOpenSubscription(sub.Name.c_str(),
EC_READ_ACCESS | EC_WRITE_ACCESS,
EC_CREATE_NEW);
if ( !hSubscription)
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Step 2: Define the subscription properties.
// Set the subscription type property (collector initiated).
vPropertyValue.Type = EcVarTypeUInt32;
vPropertyValue.UInt32Val = sub.SubscriptionType;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionType,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the Description property that contains a description
// of the subscription.
vPropertyValue.Type = EcVarTypeString;
vPropertyValue.StringVal = sub.Description.c_str();
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionDescription,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the URI property that specifies the URI of all the event sources.
vPropertyValue.Type = EcVarTypeString;
vPropertyValue.StringVal = sub.URI.c_str();
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionURI,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the Query property that defines the query used by the event
// source to select events that are forwarded to the event collector.
vPropertyValue.Type = EcVarTypeString;
vPropertyValue.StringVal = sub.Query.c_str();
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionQuery,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the Log File property that specifies where the forwarded events
// will be stored.
vPropertyValue.Type = EcVarTypeString;
vPropertyValue.StringVal = sub.DestinationLog.c_str();
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionLogFile,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the ConfigurationMode property that specifies the mode in which events
// are delivered.
vPropertyValue.Type = EcVarTypeUInt32;
vPropertyValue.UInt32Val = sub.ConfigMode;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionConfigurationMode,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// If the Configuration Mode is Custom, set the DeliveryMode, DeliveryMaxItems,
// HeartbeatInterval, and DeliveryMaxLatencyTime properties.
if ( sub.ConfigMode == EcConfigurationModeCustom)
{
// Set the DeliveryMode property that defines how events are delivered.
// Events can be delivered through either a push or pull model.
vPropertyValue.Type = EcVarTypeUInt32;
vPropertyValue.UInt32Val = sub.DeliveryMode;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionDeliveryMode,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the DeliveryMaxItems property that specifies the maximum number of
// events that can be batched when forwarded from the event sources.
vPropertyValue.Type = EcVarTypeUInt32;
vPropertyValue.UInt32Val = sub.MaxItems;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionDeliveryMaxItems,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the HeartbeatInterval property that defines the time interval, in
// seconds, that is observed between the heartbeat messages.
vPropertyValue.Type = EcVarTypeUInt32;
vPropertyValue.UInt32Val = sub.HeartbeatInerval;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionHeartbeatInterval,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the DeliveryMaxLatencyTime property that specifies how long, in
// seconds, the event source should wait before forwarding events.
vPropertyValue.Type = EcVarTypeUInt32;
vPropertyValue.UInt32Val = sub.MaxLatencyTime;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionDeliveryMaxLatencyTime,
NULL,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
}
// Set the ContentFormat property that specifies the format for the event content.
vPropertyValue.Type = EcVarTypeUInt32;
vPropertyValue.UInt32Val = sub.ContentFormat;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionContentFormat,
0,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the ReadExistingEvents property that is used to enable or disable whether
// existing events are forwarded.
vPropertyValue.Type = EcVarTypeBoolean;
vPropertyValue.BooleanVal = sub.ReadExistingEvents;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionReadExistingEvents,
0,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the Enabled property that is used to enable or disable the subscription
// or to obtain the current status of a subscription.
vPropertyValue.Type = EcVarTypeBoolean;
vPropertyValue.BooleanVal = sub.SubscriptionStatus;
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionEnabled,
0,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Set the TransportName property that determines the type of
// transport used by the subscription.
vPropertyValue.Type = EcVarTypeString;
vPropertyValue.StringVal = sub.TransportName.c_str();
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionTransportName,
0,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Required:
// Set the AllowedSourceDomainComputers property to the specified SDDL.
vPropertyValue.Type = EcVarTypeString;
vPropertyValue.StringVal = sub.AllowedSourceDomainComputers.c_str();
if (!EcSetSubscriptionProperty(hSubscription,
EcSubscriptionAllowedSourceDomainComputers,
0,
&vPropertyValue))
{
dwRetVal = GetLastError();
goto Cleanup;
}
//----------------------------------------------
// Step 3: Save the subscription.
// Save the subscription with the associated properties
// This will create the subscription and store it in the
// subscription repository
if( !EcSaveSubscription(hSubscription, NULL) )
{
dwRetVal = GetLastError();
goto Cleanup;
}
// Step 4: Close the subscription.
Cleanup:
if(hSubscription)
EcClose(hSubscription);
if (dwRetVal != ERROR_SUCCESS)
{
FormatMessageW( FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM,
NULL,
dwRetVal,
0,
(LPWSTR) &lpwszBuffer,
0,
NULL);
if (!lpwszBuffer)
{
wprintf(L"Failed to FormatMessage. Operation Error Code: %u." \
L"Error Code from FormatMessage: %u\n", dwRetVal, GetLastError());
return;
}
wprintf(L"\nFailed to Perform Operation.\nError Code: %u\n" \
L" Error Message: %s\n", dwRetVal, lpwszBuffer);
LocalFree(lpwszBuffer);
}
}
DWORD GetProperty(EC_HANDLE hSubscription,
EC_SUBSCRIPTION_PROPERTY_ID propID,
DWORD flags,
std::vector<BYTE>& buffer,
PEC_VARIANT& vProperty)
{
DWORD dwBufferSize, dwRetVal = ERROR_SUCCESS;
buffer.resize(sizeof(EC_VARIANT));
if (!hSubscription)
return ERROR_INVALID_PARAMETER;
// Get the value for the specified property.
if (!EcGetSubscriptionProperty(hSubscription,
propID,
flags,
(DWORD) buffer.size(),
(PEC_VARIANT)&buffer[0],
&dwBufferSize) )
{
dwRetVal = GetLastError();
if (ERROR_INSUFFICIENT_BUFFER == dwRetVal)
{
dwRetVal = ERROR_SUCCESS;
buffer.resize(dwBufferSize);
if (!EcGetSubscriptionProperty(hSubscription,
propID,
flags,
(DWORD) buffer.size(),
(PEC_VARIANT)&buffer[0],
&dwBufferSize))
{
dwRetVal = GetLastError();
}
}
}
if (dwRetVal == ERROR_SUCCESS)
{
vProperty = (PEC_VARIANT) &buffer[0];
}
else
{
vProperty = NULL;
}
return dwRetVal;
}
Validate that the subscription works correctly
On the event collector computer complete the following procedure:
Run the following command from an elevated privilege command prompt to get the runtime status of the subscription:
wecutil gr <subscriptionID>
Verify that the event source has connected. You might need to wait until the refresh interval specified in the policy is over after you create the subscription for the event source to be connected.
Run the following command to get the subscription information:
wecutil gs <subscriptionID>
Get the DeliveryMaxItems value from the subscription information.
On the event source computer, raise the events that match the query from the event subscription. The DeliveryMaxItems number of events must be raised for the events to be forwarded.
On the event collector computer, validate that the events have been forwarded to the ForwardedEvents log or to the log specified in the subscription.
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for