3.2.5.2.3.6 INtmsObjectInfo1::CreateNtmsMediaW (Opnum 8)

  • Article

The CreateNtmsMediaW method creates a new offline medium for a media pool, with strings encoded using Unicode.

 HRESULT CreateNtmsMediaW(
   [in, out] LPNTMS_OBJECTINFORMATIONW lpMedia,
   [in, out, size_is(*lpdwListBufferSize), length_is(dwListCount)] 
     LPNTMS_OBJECTINFORMATIONW lpList,
   [in] DWORD* lpdwListBufferSize,
   [in] DWORD dwListCount,
   [in] DWORD dwOptions
 );

lpMedia: A pointer to an NTMS_OBJECTINFORMATIONW (section 2.2.4.21) structure describing the properties of the medium to create.

lpList: An array of NTMS_OBJECTINFORMATIONW (section 2.2.4.21) structures specifying the sides of the new medium.

lpdwListBufferSize: A pointer to the size of lpList, in bytes.

dwListCount: The number of elements in the lpList array.

dwOptions: A bitmap of creation options.

If a medium with the specified on-media identifier already exists in the system<70> and the client does not want to duplicate the identifier, the client MUST set dwOptions to NTMS_ERROR_ON_DUPLICATION (0x00000001) and the server MUST NOT create a medium with the specified identifier.

If a medium with the specified on-media identifier already exists in the system<71> and the client wants to duplicate the identifier, the client MUST set dwOptions to 0x00000000 and the server MUST create a medium with the specified identifier.

If a medium with the specified on-media identifier does not exist in the system,<72>there is no change in the server behavior due to this option.

Return value/code

Description

0x00000000

S_OK

The call was successful.

0x80070005

ERROR_ACCESS_DENIED

NTMS_USE_ACCESS to the media pool or offline media library is denied; other security errors are possible but indicate a security subsystem error.

0x80070008

ERROR_NOT_ENOUGH_MEMORY

An allocation failure occurred during processing.

0x80070057

ERROR_INVALID_PARAMETER

Invalid input parameter.

0x800710CC

ERROR_INVALID_MEDIA

The option NTMS_ERROR_ON_DUPLICATION was provided, and a medium with this on-media identifier already exists.

0x800710CE

ERROR_INVALID_MEDIA_POOL

The specified media pool either does not exist, or is not a valid import or application pool.

0x800710D9

ERROR_DATABASE_FAILURE

The database is inaccessible or damaged.

0x800710DA

ERROR_DATABASE_FULL

The database is full.

0x800710DB

ERROR_MEDIA_INCOMPATIBLE

The number of specified sides does not match the number of sides associated with the media type of the media pool.

Upon receiving this message, the server MUST verify that both lpMedia and lpList are not NULL. If parameter validation fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER (0x80070057).

If dwOptions is NTMS_ERROR_ON_DUPLICATION (0x00000001), the server MUST verify that the medium with the specified on-media identifier does not exist.<73> If the medium with the specified on-media identifier does exist, the server MUST return ERROR_INVALID_MEDIA (0x800710CC) and take no further action.

If parameter validation succeeds, the server MUST verify that the user has the required access rights. If the client does not have the required access rights, the server MUST return ERROR_ACCESS_DENIED (0x80070005).

The server MUST create a PMID and side (or sides) for a new piece of offline media. The media MUST be placed in the media pool specified for MediaPool.

The lpMedia parameter MUST point to an NTMS_OBJECTINFORMATIONW structure. For a full list of NTMS_OBJECTINFORMATIONW members and their descriptions, see section 2.2.4.21.

The NTMS_OBJECTINFORMATIONW structure MUST meet the following criteria.

 Member

 Description

dwSize

[in] CreateNtmsMedia MUST verify that this size equals the length of a NTMS_OBJECTINFORMATION structure containing an NTMS_PMIDINFORMATIONW (section 2.2.4.32) structure. It MUST return ERROR_INVALID_PARAMETER if the size is incorrect.

dwType

[in] CreateNtmsMedia MUST verify that the value NTMS_PHYSICAL_MEDIA was provided. It returns ERROR_INVALID_PARAMETER if the provided type is incorrect.

Created

[out] Indicates the time the PMID was entered into the NTMS database.

Modified

[out] Indicates the time the PMID was last modified in the NTMS database.

ObjectGuid

[in/out] A unique identifier for the PMID. If a non-NULL value is provided, the value MUST be used as the GUID of the physical medium; otherwise a GUID MUST be generated.

Enabled

[in] Indicates whether to enable the physical medium.

dwOperationalState

[out] MUST be NTMS_READY.

szName

[in/out] CreateNtmsMedia allows an application to specify the name of a new physical medium. This enables the application to continue to use the name of a medium after moving it from one RSM computer to another. The RSM default naming selection is: for single-sided media, bar code and then label information value or sequence number; for multisided media, bar code and then sequence number.

Note that the name that appears in the RSM user interface for a partition is this name (the name assigned to the physical media object).

szDescription

[in] An optional parameter that MAY be set using CreateNtmsMedia. Provide the empty string ("\0") to avoid passing in a value for the description.

The lpList parameter MUST point to an NTMS_OBJECTINFORMATIONW structure. A full list of NTMS_OBJECTINFORMATIONW members and their descriptions can be found at 2.2.4.21.

The NTMS_OBJECTINFORMATIONW structure MUST meet the following criteria.

 Member

 Description

dwSize

[in] CreateNtmsMedia MUST verify that the provided size matches the expected length of an NTMS_OBJECTINFORMATION structure containing an NTMS_PARTITIONINFORMATION structure. It MUST return ERROR_INVALID_PARAMETER if the size is incorrect.

dwType

[in] CreateNtmsMedia MUST verify that the value NTMS_PARTITION was provided. It MUST return ERROR_INVALID_PARAMETER if the provided type is incorrect.

Created

[out] Indicates the time that the partition object was entered into the RSM database.

Modified

[out] Indicates the time that the partition object was last modified in the RSM database.

ObjectGuid

[in/out] The unique identifier for the side. If a non-NULL value is provided, the value MUST be used as the GUID of the side; otherwise, a GUID is generated.

Enabled

[in] Determines whether to enable the side.

dwOperationalState

[out] MUST be NTMS_READY.

szName

[in] The name of a new side.

szDescription

[in] An optional parameter that MAY be set using CreateNtmsMedia. Provide the empty string ("\0") to avoid passing in a value for the description.

PhysicalMedia

[out] The GUID of the newly created side object.

LogicalMedia

[in/out] An optional input parameter, as well as an output parameter. If the GUID is provided, CreateNtmsMedia MUST attempt to create a new logical media object with the pre-assigned GUID. If the GUID is not unique, CreateNtmsMedia MUST return an error.

State

[in] Any valid side state.

Side

[out] CreateNtmsMedia MUST set the side number to its offset in the partitions array.

dwOmidLabelIdLength

[in] MUST be a positive value.

CreateNtmsMedia uses the dwOmidLabelIdLength to determine the number of significant bytes in the OmidLabelId member. If the value is not correct, the recorded OmidLabelId is incorrect.

OmidLabelId

[in] MUST be a valid media label that can be recognized by server.

szOmidLabelType

[in] MUST not be an empty string.

szOmidLabelInfo

[in] MAY be the empty string.

dwMountCount

[in] Any value is accepted.

dwAllocateCount

[in] Any value is accepted.

Capacity

[in] SCSI [ANSI-131-1994] capacity code.

This member MUST NOT be used by RSM, but MAY be used by applications written to RSM for additional information about the media. For a description of what this member MUST be set to, see the hardware manufacturer's SCSI specification for possible settings.

RSM MUST update this member when it mounts the newly imported medium for the first time.

Strings sent to this method as parameters MUST be Unicode-encoded.