<div class="content" name="CreateNtmsMediaA" uuid="a5409890-e40c-48f2-8cea-d678fd381b28"><p>The CreateNtmsMediaA method creates a new offline medium for
a media pool, with strings encoded using ASCII.</p><dl>
<dd>
<div><pre> HRESULT CreateNtmsMediaA(
   [in, out] LPNTMS_OBJECTINFORMATIONA lpMedia,
   [in, out, size_is(*lpdwListBufferSize), length_is(dwListCount)] 
     LPNTMS_OBJECTINFORMATIONA lpList,
   [in] DWORD* lpdwListBufferSize,
   [in] DWORD dwListCount,
   [in] DWORD dwOptions
 );
</pre></div>
</dd></dl><p><b>lpMedia: </b>A pointer to an <a href="9252e471-a237-453a-9727-dbff3c125510" data-linktype="relative-path">NTMS_OBJECTINFORMATIONA (section 2.2.4.20)</a>
structure describing the properties of the medium to create. </p><p><b>lpList: </b>An array of
NTMS_OBJECTINFORMATIONA (section 2.2.4.20) structures specifying the <a href="8d988f06-72be-47cf-9e09-9060aa8ed897#gt_55db62c5-a84f-43b7-a037-b44ecd8fb92f" data-linktype="relative-path">sides</a> of the new medium.</p><p><b>lpdwListBufferSize: </b>A pointer to the size of
lpList, in bytes.</p><p><b>dwListCount:</b> The number of elements in the
lpList array.</p><p><b>dwOptions:</b> A bitmap of creation options.</p><dl>
<dd>
<p>If a medium with the specified <a href="8d988f06-72be-47cf-9e09-9060aa8ed897#gt_e88a9ca7-9b8d-4dca-9338-59c98e1a5f13" data-linktype="relative-path">on-media identifier</a> already
exists in the system<a id="Appendix_A_Target_65"></a><a aria-label="Product behavior note 65" href="7184b376-4ee3-4482-b9c4-f87ff22b421f#Appendix_A_65" data-linktype="relative-path">&lt;65&gt;</a> and the client does not want to
duplicate the identifier, the client MUST set <i>dwOptions</i> to
NTMS_ERROR_ON_DUPLICATION (0x00000001) and the server MUST NOT create a medium
with the specified identifier.</p>
</dd>
<dd>
<p>If a medium with the specified on-media identifier
already exists in the system<a id="Appendix_A_Target_66"></a><a aria-label="Product behavior note 66" href="7184b376-4ee3-4482-b9c4-f87ff22b421f#Appendix_A_66" data-linktype="relative-path">&lt;66&gt;</a> and the
client wants to duplicate the identifier, the client MUST set <i>dwOptions</i>
to 0x00000000 and the server MUST create a medium with the specified
identifier.</p>
</dd>
<dd>
<p>If a medium with the specified on-media identifier
does not exist in the system,<a id="Appendix_A_Target_67"></a><a aria-label="Product behavior note 67" href="7184b376-4ee3-4482-b9c4-f87ff22b421f#Appendix_A_67" data-linktype="relative-path">&lt;67&gt;</a> there is
no change in the server behavior due to this option.</p>
</dd>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Return value/code</p>
   </th>
   <th>
   <p>Description</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000 S_OK</td>
  <td>The call was successful.</td>
 </tr><tr>
  <td>0x80070005 ERROR_ACCESS_DENIED</td>
  <td>NTMS_USE_ACCESS to the media pool or offline media library is denied; other security errors are possible but indicate a security subsystem error.</td>
 </tr><tr>
  <td>0x80070008 ERROR_NOT_ENOUGH_MEMORY</td>
  <td>An allocation failure occurred during processing.</td>
 </tr><tr>
  <td>0x80070057 ERROR_INVALID_PARAMETER</td>
  <td>Invalid input parameter.</td>
 </tr><tr>
  <td>0x800710CC ERROR_INVALID_MEDIA</td>
  <td>The option NTMS_ERROR_ON_DUPLICATION was provided, and a medium with this on-media identifier already exists.</td>
 </tr><tr>
  <td>0x800710CE ERROR_INVALID_MEDIA_POOL</td>
  <td>The specified media pool either does not exist, or is not a valid import or application pool.</td>
 </tr><tr>
  <td>0x800710D9 ERROR_DATABASE_FAILURE</td>
  <td>The database is inaccessible or damaged.</td>
 </tr><tr>
  <td>0x800710DA ERROR_DATABASE_FULL</td>
  <td>The database is full.</td>
 </tr><tr>
  <td>0x800710DB ERROR_MEDIA_INCOMPATIBLE</td>
  <td>The number of specified sides does not match the number of sides associated with the media type of the media pool.</td>
 </tr></tbody></table>
</dd></dl><p>Upon receiving this message, the server MUST verify that
both <i>lpMedia</i> and <i>lpList</i> are not NULL. If parameter validation
fails, the server MUST immediately fail the operation and return ERROR_INVALID_PARAMETER
(0x80070057).</p><p>If dwOptions is NTMS_ERROR_ON_DUPLICATION (0x00000001), the
server MUST verify that the medium with the specified on-media identifier does
not exist.<a id="Appendix_A_Target_68"></a><a aria-label="Product behavior note 68" href="7184b376-4ee3-4482-b9c4-f87ff22b421f#Appendix_A_68" data-linktype="relative-path">&lt;68&gt;</a> If the medium with the
specified on-media identifier does exist, the server MUST return
ERROR_INVALID_MEDIA (0x800710CC) and take no further action.</p><p>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).</p><p>The server MUST create a physical media object (PMID) and
side (or sides) for a new piece of offline media. For a list of <a href="5ce300f7-e1ec-4b7d-a9f1-2570e5eb9dbf" data-linktype="relative-path">NTMS_PMIDINFORMATIONA</a>
members and their descriptions, see section 2.2.4.31. The media MUST be placed
in the media pool specified for <b>MediaPool</b>.</p><p>The <i>lpMedia</i> parameter MUST point to an
NTMS_OBJECTINFORMATIONA structure. A full list of NTMS_OBJECTINFORMATIONA
members and their descriptions can be found at 2.2.4.20.</p><p>The member that NTMS_OBJECTINFORMATIONA MUST contain is
specified in the left column of the following table; the criteria that the
respective member MUST adhere to are specified in the right column.</p><table><thead>
  <tr>
   <th>
   <p> Member </p>
   </th>
   <th>
   <p> Description </p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>dwSize</td>
  <td>[in] CreateNtmsMedia MUST verify that this size equals the length of an NTMS_OBJECTINFORMATION structure containing an NTMS_PMIDINFORMATION structure. It MUST return ERROR_INVALID_PARAMETER if the size is incorrect.</td>
 </tr><tr>
  <td>dwType</td>
  <td>[in] CreateNtmsMedia MUST verify that the value NTMS_PHYSICAL_MEDIA was provided. It MUST return ERROR_INVALID_PARAMETER if the provided type is incorrect.</td>
 </tr><tr>
  <td>Created</td>
  <td>[out] Indicates the time the physical media object was entered into the NTMS database.</td>
 </tr><tr>
  <td>Modified</td>
  <td>[out] Indicates the time the PMID was last modified in the NTMS database.</td>
 </tr><tr>
  <td>ObjectGuid</td>
  <td>[in/out] A unique identifier for the physical media object (PMID). If a non-NULL value is provided, the value MUST be used as the GUID of the physical media; otherwise a GUID MUST be generated.</td>
 </tr><tr>
  <td>Enabled</td>
  <td>[in] Indicates whether to enable the physical media.</td>
 </tr><tr>
  <td>dwOperationalState</td>
  <td>[out] MUST be NTMS_READY.</td>
 </tr><tr>
  <td>szName</td>
  <td>[in/out] CreateNtmsMedia allows an application to specify the name of a new physical medium. This functionality enables the application to continue to use the name of a medium after moving the medium 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).</td>
 </tr><tr>
  <td>szDescription</td>
  <td>[in] An optional parameter that MAY be set using CreateNtmsMedia. Provide the empty string (&#34;\0&#34;) to avoid passing in a value for the description.</td>
 </tr></tbody></table><p>The <i>lpList</i> parameter MUST point to an
NTMS_OBJECTINFORMATIONA structure. A full list of NTMS_OBJECTINFORMATIONA
members and their descriptions can be found at 2.2.4.20.</p><p>The NTMS_OBJECTINFORMATIONA structure MUST meet the
following criteria. </p><table><thead>
  <tr>
   <th>
   <p> Member </p>
   </th>
   <th>
   <p> Description </p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>dwSize</td>
  <td>[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.</td>
 </tr><tr>
  <td>dwType</td>
  <td>[in] CreateNtmsMedia MUST verify that the value NTMS_PARTITION was provided. It MUST return ERROR_INVALID_PARAMETER if the provided type is incorrect.</td>
 </tr><tr>
  <td>Created</td>
  <td>[out] Indicates the time that the partition object was entered into the RSM database.</td>
 </tr><tr>
  <td>Modified</td>
  <td>[out] Indicates the time that the partition object was last modified in the RSM database.</td>
 </tr><tr>
  <td>ObjectGuid</td>
  <td>[in/out] A 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 MUST be generated.</td>
 </tr><tr>
  <td>Enabled</td>
  <td>[in] Determines whether to enable the side.</td>
 </tr><tr>
  <td>dwOperationalState</td>
  <td>[out] MUST be NTMS_READY.</td>
 </tr><tr>
  <td>szName</td>
  <td>[in] The name of a new side.</td>
 </tr><tr>
  <td>szDescription</td>
  <td>[in] An optional parameter that MAY be set using CreateNtmsMedia. Provide the empty string (&#34;\0&#34;) to avoid passing in a value for the description.</td>
 </tr><tr>
  <td>PhysicalMedia</td>
  <td>[out] The GUID of the newly created side object.</td>
 </tr><tr>
  <td>LogicalMedia</td>
  <td>[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.</td>
 </tr><tr>
  <td>State</td>
  <td>[in] Any valid side state.</td>
 </tr><tr>
  <td>Side</td>
  <td>[out] CreateNtmsMedia sets the side number to its offset in the Partitions array.</td>
 </tr><tr>
  <td>dwOmidLabelIdLength</td>
  <td>[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.</td>
 </tr><tr>
  <td>OmidLabelId</td>
  <td>[in] MUST be a valid media label that can be recognized by server.</td>
 </tr><tr>
  <td>szOmidLabelType</td>
  <td>[in] MUST not be an empty string.</td>
 </tr><tr>
  <td>szOmidLabelInfo</td>
  <td>[in] MAY be the empty string.</td>
 </tr><tr>
  <td>dwMountCount</td>
  <td>[in] Any value is accepted.</td>
 </tr><tr>
  <td>dwAllocateCount</td>
  <td>[in] Any value is accepted.</td>
 </tr><tr>
  <td>Capacity</td>
  <td>[in] SCSI [ANSI-131-1994] capacity code. This member MUST not be used by the RSM client, 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&#39;s SCSI specification for possible settings. The RSM server updates this member when it mounts the newly imported medium for the first time.&lt;69&gt;</td>
 </tr></tbody></table><p>Strings sent to this method as parameters MUST be
ASCII-encoded.</p></div>