3.2.5.2.3 NetrJobEnum (Opnum 2)

  • Article

The NetrJobEnum method MUST return an enumeration of all AT tasks on the specified server. 

 NET_API_STATUS NetrJobEnum(
   [in, string, unique] ATSVC_HANDLE ServerName,
   [in, out] LPAT_ENUM_CONTAINER pEnumContainer,
   [in] DWORD PreferedMaximumLength,
   [out] LPDWORD pTotalEntries,
   [in, out, unique] LPDWORD pResumeHandle
 );

ServerName: Pointer to a Unicode string that MUST specify the server. The client MUST map this string to an RPC binding handle. The server MUST ignore this parameter. For more information, see [C706] sections 4.3.5 and 5.1.5.2.

pEnumContainer:  Pointer to an AT_ENUM_CONTAINER (section 2.3.5) structure that MUST contain a count of the number of entries returned and a buffer that contains the entries. The client MUST send a pointer to this structure to the server with the Buffer field set to NULL; upon return the Buffer field MUST contain a pointer to an array of AT_ENUM structures.

PreferedMaximumLength: MUST contain the preferred maximum length, in bytes, of data to be returned. A value of 0xFFFFFFFF MUST indicate no preferred maximum length.

pTotalEntries: Pointer to a value that MUST receive the total number of tasks in the list, beyond the position specified by pResumeHandle.

pResumeHandle: MUST be a pointer to an index into the list of tasks. This value indicates the index number at which the enumeration MUST start.

Return Values: For more information on return codes, see section 2.3.14, or Win32 Error Codes in [MS-ERREF] section 2.1.

In response to this request the server MUST:

  • Check the Buffer field in pEnumContainer. If it is not set to NULL, set pTotalEntries to 0 and return ERROR_INVALID_PARAMETER.

  • Verify that pResumeHandle contains a 0-based index number within the valid range of tasks in the list, and if not, set pTotalEntries to 0 and return ERROR_SUCCESS.

  • Return ERROR_ACCESS_DENIED if the caller does not have administrative privileges on the server.

  • Enumerate tasks in the AT task store, starting the enumeration at the ordinal position given by the DWORD value pointed to by the pResumeHandle parameter.

  • Calculate the size of the AT_ENUM array buffer as follows. If PreferedMaximumLength is 0xFFFFFFFF, choose a size equal to ((sizeof(AT_ENUM)+132) * number of tasks). If PreferedMaximumLength is not 0xFFFFFFFF, choose a size equal to the highest even number smaller or equal to PreferedMaximumLength. In both cases, make sure that the size is not greater than 65536 and not smaller than (sizeof(AT_ENUM)+520).

  • Allocate a buffer of this size and return the address of the buffer in the Buffer field of the AT_ENUM_CONTAINER structure pointed to by the pEnumContainer parameter.

  • Initialize the buffer to hold an array of AT_ENUM structures, with field values copied from as many enumerated tasks as fit, and initialize the EntriesRead field of the AT_ENUM_CONTAINER structure to the number of entries that fit in the buffer.

  • Return the number of tasks enumerated in the pTotalEntries parameter, beyond the position specified by pResumeHandle.

  • Return the status code ERROR_SUCCESS if all the enumerated tasks fit in the buffer and set pResumeHandle to 0; otherwise, return ERROR_MORE_DATA  and increment the value pointed to by the pResumeHandle parameter by the value of the EntriesRead field.

  • MUST return ERROR_SUCCESS if the call was successful.

If any errors are raised during the processing, they are returned. For more information about return codes, see section 2.3.14 and Win32 Error Codes in [MS-ERREF] section 2.1.