Platform SDK: Removable Storage Manager

CreateNtmsMedia

The CreateNtmsMedia function creates a PMID and side (or sides) for a new piece of offline media. The media is placed in the media pool specified for lpPhysicalMedia.

DWORD WINAPI CreateNtmsMedia(
  HANDLE hSession,
  LPNTMS_OBJECTINFORMATION lpPhysicalMedia,
  LPNTMS_OBJECTINFORMATION lpPartitions,
  DWORD dwOptions
);

Parameters

hSession

Handle to the session returned by the OpenNtmsSession function.

lpPhysicalMedia

A required input parameter, providing information about the medium to create. See Remarks NTMS_OBJECTINFORMATION and NTMS_PMIDINFORMATION for a description of the applicable members.

lpPartitions

A required input parameter, pointing to an array of sides associated with the medium. See NTMS_OBJECTINFORMATION and NTMS_PARTITIONINFORMATION for a description of the fields.

dwOptions

Defines processing behavior:

Value	Description
0	Default value. Allows the creation of a duplicate medium with a duplicate OMID.
NTMS_ERROR_ON_DUPLICATION	Returns an error and does not create the medium if a medium with the specified OMID already exists on the system.

Return Values

Value	Meaning
ERROR_SUCCESS	The function executed successfully.
ERROR_INVALID_PARAMETER	Missing parameter or invalid object information size or object type.
ERROR_INVALID_HANDLE	Bad or missing session handle.
ERROR_INVALID_MEDIA_POOL	Media pool specified either does not exist, or is not a valid Import or Application pool.
ERROR_INVALID_MEDIA	An entry already exists for a medium with this barcode.
ERROR_MEDIA_INCOMPATIBLE	Number of specified sides does not match the number of sides associated with the media pool's media type.
ERROR_NOT_ENOUGH_MEMORY	Memory allocation failure during processing.
ERROR_ACCESS_DENIED	NTMS_USE_ACCESS to the media pool or the offline library is denied; other security errors are also possible but indicate a security subsystem error.
ERROR_DATABASE_FAILURE	Database inaccessible or damaged.
ERROR_DATABASE_FULL	Database is full.
ERROR_DUPLICATE_OMID	The option NTMS_ERROR_ON_DUPLICATE was provided and a medium already exists with this OMID.

Remarks

The lpPhysicalMedia parameter must point to an NTMS_OBJECTINFORMATION structure, whose dwType parameter is of the value NTMS_PHYSICAL_MEDIA, with the following information, included is a list of members and descriptions for the NTMS_OBJECTINFORMATION structure.

Member	Description
dwSize	[In] CreateNtmsMedia verifies that the provided size matches the expected length of an NTMS_OBJECTINFORMATION structure containing NTMS_PMIDINFORMATION. It returns ERROR_INVALID_PARAMETER if the size is incorrect.
dwType	[In] CreateNtmsMedia verifies that the value NTMS_PHYSICAL_MEDIA was provided. It returns ERROR_INVALID_PARAMETER if the provided type is incorrect.
Created	[Out] Indicates time the physical media object was entered into the NTMS database.
Modified	[Out] Indicates time the physical media object was entered into the NTMS database.
ObjectGuid	[In/Out] This field is the unique identifier for the physical media object (PMID). If a non-NULL value is provided, the value is used as the GUID of the Physical Medium, otherwise a GUID is generated.
Enabled	[In] ndicates whether or not the physical medium should be enabled.
dwOperationalState	[Out] Always NTMS_READY.
szName	[In/Out] CreateNtmsMedia contains functionality to allow an application to specify the name of a new physical medium. This enables the application to carry the name of a medium forward when moving it from one RSM computer to another. The RSM default naming selection is: for single sided: Barcode, then Label Info value or Sequence Number;. for multi-sided media Barcode 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] The description is an optional parameter that may be set using CreateNtmsMedia. Provide the empty string ("\0") to avoid passing in a value for the description.

The following is a list of members and descriptions for the NTMS_PMIDINFORMATION structure.

Member	Description
CurrentLibrary	[In] Must be either the NULL_GUID, or the GUID of the Offline library. CreateNtmsMedia function returns an error if any other GUID is provided.
MediaPool	[In] Must be the GUID of a valid Import or Application pool. CreateNtmsMedia verifies that this is the GUID of a valid Import or Application Pool. It also verifies that the number of partitions provided are correct for the media type associated with this media pool.
Location	[Out] This field will be set to the NULL_GUID.
LocationType	[Out] Always NTMS_STORAGESLOT, as are all media in the offline library.
HomeSlot	Output parameter. Always the NULL_GUID.
MediaType	[Out] CreateNtmsMedia sets the media type to the media type associated with the media pool provided.
szBarCode	[In/Out] The barcode is stripped of any ending spaces. CreateNtmsMedia does not perform any additional attempts at verifying the validity of the barcode.
BarCodeState	[Out] The BarCodeState is set to NTMS_BARCODESTATE_UNREADABLE if the value passed in for szBarCode is an empty string, otherwise it is set to NTMS_BARCODESTATE_OK.
szSequenceNumber	[Out] CreateNtmsMedia assigns the newly-created medium a sequence number, which is returned in this field.
MediaState	[Out] CreateNtmsMedia sets the MediaState to NTMS_MEDIASTATE_IDLE.
dwNumberOfPartitions	[In] dwNumberOfPartitions defines the number of NTMS_OBJECTINFORMATION structures representing sides for this medium. CreateNtmsMedia checks to ensure that the number of sides specified matches the number of sides implied by the media pool to which it is to be assigned. If they do not match, ERROR_MEDIA_INCOMPATIBLE is returned.
dwMediaTypeCode	[In] The dwMediaTypeCode member is the SCSI media type code. This field is not used by RSM, but may be used by applications written to RSM for additional information about the media. For a description of what this field should be set to, see the Hardware Manufacturer's SCSI spec for possible settings. RSM updates this field when it mounts the newly-imported medium for the first time.
dwDensityCode	[In] The dwDensityCode member is the SCSI density code. This field is not used by RSM, but may be used by applications written to RSM for additional information about the media. For a description of what this field should be set to, see the Hardware Manufacturer's SCSI spec for possible settings. RSM updates this field when it mounts the newly-imported medium for the first time

Specifying the Partition Information

The lpPartitions parameter must point to an NTMS_OBJECTINFORMATION structure whose dwType is NTMS_PARTITION with the following information.

Member	Description
dwSize	[In] CreateNtmsMedia verifies that the provided size matches the expected length of an NTMS_OBJECTINFORMATION structure containing NTMS_PARTITIONINFORMATION. It returns ERROR_INVALID_PARAMETER if the size is incorrect.
dwType	[In] CreateNtmsMedia verifies that the value NTMS_PARTITIONwas provided. It returns 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 entered into the RSM database.
ObjectGuid	[In/Out] This field is the unique identifier for the side. If a non-NULL value is provided, the value is used as the GUID of the side; otherwise, a GUID is generated.
Enabled	[In] Determines whether or not the side should be enabled.
dwOperationalState	[Out] Always NTMS_READY.
szName	CreateNtmsMedia allows an application to specify the name of a new side.
szDescription	[In] The description is 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] CreateNtmsMedia sets this field to the GUID of the newly-created side object.
LogicalMedia	[In/Out] LogicalMedia is an optional input parameter, as well as an output parameter. If the LogicalMedia GUID is provided, CreateNtmsMedia attempts to create a new logical media object with the preassigned GUID. If the GUID is not unique, CreateNtmsMedia returns an error.
State	[In] Any valid side state is acceptable.
Side	[Out] CreateNtmsMedia sets the side number to its offset in the Partitions array.
dwOmidLabelIdLength	[In] Must be a positive value. CreateNtmsMedia uses the dwOmidIdLabelIdLength to determine the number of significant bytes in the OmidLabelId member. If the value is not correct, the recorded OmidLabelId is incorrect.
OmidLabelId	[In] This must represent a valid media label that can be recognized by an installed MLL.
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] The Capacity field is the SCSI capacity code. This field is not used by RSM, but may be used by applications written to RSM for additional information about the media. For a description of what this field should be set to, see the Hardware Manufacturer's SCSI spec for possible settings. RSM updates this field when it mounts the newly-imported medium for the first time.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntmsapi.h.
  Library: Use Ntmsapi.lib.