3.1 IIS Application Host Administration Server Details
3.1.4 Message Processing Events and Sequencing Rules
3.1.4.7 IAppHostConfigLocation
ppSectionGroups: Contains an IAppHostSectionGroup that contains declarations.
Return Values: The server MUST return zero if it successfully processes the message that is received from the client. In this case, *ppSectionGroups is not NULL. If processing fails, the server MUST return a nonzero HRESULT code as defined in [MS-ERREF]. The following table describes the error conditions that MUST be handled and the corresponding error codes. A server MAY return
additional implementation-specific error codes.
Return value/code Description 0X00000000
NO_ERROR
The operation completed successfully.
0X80070057
ERROR_INVALID_PARAMETER
One or more parameters are incorrect or null.
0X00000008
ERROR_NOT_ENOUGH_MEMORY
Not enough memory is available to process this command.
3.1.4.7 IAppHostConfigLocation
The IAppHostConfigLocation interface provides methods that access the IAppHostElement objects that are contained in a specific hierarchy subpath in a specified IAppHostConfigFile. IAppHostConfigFile maps to a specific hierarchy path in the administration system, as specified in section 3.1.4.6.
Each IAppHostConfigFile can optionally contain subpaths within it. Each subpath is represented by an IAppHostConfigLocation object. The object contains a collection of IAppHostElement objects, with the guarantee that each IAppHostConfigLocation contains at most one IAppHostElement object of the same name (in other words, the IAppHostElement object name is a key into the collection).
The IAppHostConfigLocation interface inherits opnums 0–2 from the IUnknown interface.
Methods in RPC Opnum Order Method Description
Path Opnum: 3
Count Opnum: 4
Item Opnum: 5
AddConfigSection Opnum: 6 DeleteConfigSection Opnum: 7
3.1.4.7.1 Path (Opnum 3)
The Path method is received by the server in an RPC_REQUEST packet. In response, the server returns the subpath for the specific IAppHostConfigLocation.
[propget] HRESULT Path(
[out, retval] BSTR* pbstrLocationPath );
pbstrLocationPath: Contains the path for the specific IAppHostConfigLocation. If the path is "" (an empty string), it represents the same path as the containing IAppHostConfigFile.
Return Values: The server MUST return zero if it successfully processes the message that is received from the client. In this case, *pbstrLocationPath is not NULL. If processing fails, the server MUST return a nonzero HRESULT code as defined in [MS-ERREF]. The following table describes the error conditions that MUST be handled and the corresponding error codes. A server MAY return
additional implementation-specific error codes.
Return value/code Description 0X00000000
NO_ERROR
The operation completed successfully.
0X80070057
ERROR_INVALID_PARAMETER
One or more parameters are incorrect or null.
0X00000008
ERROR_NOT_ENOUGH_MEMORY
Not enough memory is available to process this command.
3.1.4.7.2 Count (Opnum 4)
The Count method is received by the server in an RPC_REQUEST packet. In response, the server returns the number of IAppHostElement objects that are defined or exist at the specified
IAppHostConfigLocation.
[propget] HRESULT Count(
[out, retval] DWORD* pcCount );
pcCount: The integer count of the number of IAppHostElement objects at the specified IAppHostConfigLocation.
Return Values: The server MUST return zero if it successfully processes the message that is received from the client. If processing fails, the server MUST return a nonzero HRESULT code as defined in [MS-ERREF]. The following table describes the error conditions that MUST be handled and the corresponding error codes. A server MAY return additional implementation-specific error codes.
Return value/code Description 0X00000000
NO_ERROR
The operation completed successfully.
0X80070057
ERROR_INVALID_PARAMETER
One or more parameters are incorrect or null.
3.1.4.7.3 Item (Opnum 5)
The Item method is received by the server in an RPC_REQUEST packet. In response, the server returns the IAppHostElement object that corresponds to the specific index parameter.
[propget, id(DISPID_VALUE)] HRESULT Item(
[in] VARIANT cIndex,
[out, retval] IAppHostElement** ppSection );
cIndex: A VARIANT, which is used to specify the IAppHostElement object to retrieve. If the VARIANT is of type integer, the index is a zero-based index to the collection of IAppHostElement objects, where 0 indicates the first IAppHostElement object, 1 the second, and so on. If the VARIANT is of type string, the index is the name of the IAppHostElement object that is retrieved.
ppSection: Contains an IAppHostElement object, if found.
Return Values: The server MUST return zero if it successfully processes the message that is received from the client. In this case, *ppSection is not NULL. If processing fails, the server MUST return a nonzero HRESULT code as defined in [MS-ERREF]. The following table describes the error
conditions that MUST be handled and the corresponding error codes. A server MAY return additional implementation-specific error codes.
Return value/code Description 0X00000000
NO_ERROR
The operation completed successfully.
0X80070585
ERROR_INVALID_INDEX
The integer index specified by cIndex is invalid or the element with name specified by cIndex could not be found.
Return value/code Description 0X00000008
ERROR_NOT_ENOUGH_MEMORY
Not enough memory is available to process this command.
0X80070013
ERROR_INVALID_DATA
Configuration data or schema on the server are malformed or corrupted.
3.1.4.7.4 AddConfigSection (Opnum 6)
The AddConfigSection method is received by the server in an RPC_REQUEST packet. In response, the server attempts to create a new empty IAppHostElement and add it to the specified
IAppHostConfigLocation. The server MAY choose to create the IAppHostElement object in memory only and not persist it to permanent storage, such as a disk file, until later.
HRESULT AddConfigSection(
[in] BSTR bstrSectionName,
[out, retval] IAppHostElement** ppAdminElement );
bstrSectionName: The name of the new IAppHostElement section to add.
ppAdminElement: Contains a newly created IAppHostElement.
Return Values: The server MUST return zero if it successfully processes the message that is received from the client. In this case, *ppAdminElement is not NULL. If processing fails, the server MUST return a nonzero HRESULT code as defined in [MS-ERREF]. The following table describes the error conditions that MUST be handled and the corresponding error codes. A server MAY return
additional implementation-specific error codes.
Return value/code Description 0X00000000
NO_ERROR
The operation completed successfully.
0X80070057
ERROR_INVALID_PARAMETER
One or more parameters are incorrect or null.
0X800700B7
ERROR_ALREADY_EXISTS
A configuration element with the name specified by bstrSectionName already exists.
0X80070013
ERROR_INVALID_DATA
Configuration data or schema on the server are malformed or corrupted.
0X80070021
ERROR_LOCK_VIOLATION
The instance is not editable.
3.1.4.7.5 DeleteConfigSection (Opnum 7)
The DeleteConfigSection method is received by the server in an RPC_REQUEST packet. In response, the server attempts to delete the IAppHostElement of the specified index.
HRESULT DeleteConfigSection(
[in] VARIANT cIndex );
cIndex: A VARIANT, which is used to specify the IAppHostElement object to delete. If the VARIANT is of type integer, the index is a zero-based index to the collection of IAppHostElement objects, where 0 indicates the first IAppHostElement object, 1 the second, and so on. If the VARIANT is of type string, the index is the name of the IAppHostElement object being retrieved.
Return Values: The server MUST return zero if it successfully processes the message that is received from the client. If processing fails, the server MUST return a nonzero HRESULT code as defined in [MS-ERREF]. The following table describes the error conditions that MUST be handled and the corresponding error codes. A server MAY return additional implementation-specific error codes.
Return value/code Description 0X00000000
NO_ERROR
The operation completed successfully.
0X80070057
ERROR_INVALID_PARAMETER
One or more parameters are incorrect or null.
0X80070013
ERROR_INVALID_DATA
Configuration data or schema on the server are malformed or corrupted.
0X80070021
ERROR_LOCK_VIOLATION
The instance is not editable.
0X80070585
ERROR_INVALID_INDEX
The integer index specified by cIndex is invalid, or the element with name specified by cIndex could not be found.
0X00000008
ERROR_NOT_ENOUGH_MEMORY
Not enough memory is available to process this command.