Dela via

Gränssnittsformat för Urklipp

  • Artikel

Shell Urklippsformat används för att identifiera vilken typ av Shell-data som överförs via Urklipp. De flesta Format för Urklipp i Shell identifierar en typ av data, till exempel en lista med filnamn eller pekare till objektidentifierarlistor (PIDL). Vissa format används dock för kommunikation mellan källa och mål. De kan påskynda dataöverföringsprocessen genom att stödja Shell-åtgärder, till exempel optimerad flytt och delete_on_paste. Shell-data finns alltid i ett dataobjekt som använder en FORMATETC- struktur som ett mer allmänt sätt att karakterisera data. Strukturens cfFormat medlem är inställd på Urklippsformatet för det specifika dataobjektet. De andra medlemmarna tillhandahåller ytterligare information, till exempel mekanismen för dataöverföring. Data finns i en tillhörande STGMEDIUM- struktur.

Not

Standardformatidentifierare för Urklipp har formuläret CF_XXX. Ett vanligt exempel är CF_TEXT, som används för överföring av ANSI-textdata. Dessa identifierare har fördefinierade värden och kan användas direkt med FORMATETC- strukturer. Med undantag för CF_HDROPär shell-formatidentifierare inte fördefinierade. Med undantag för DragWindow har de formuläret CFSTR_XXX. För att skilja dessa värden från fördefinierade format kallas de ofta bara format. Men till skillnad från fördefinierade format måste de registreras av både källa och mål innan de kan användas för att överföra data. Om du vill registrera ett Shell-format inkluderar du shlobj.h-huvudfilen och skickar CFSTR_XXX formatidentifierare till RegisterClipboardFormat. Den här funktionen returnerar ett giltigt formatvärde för Urklipp som sedan kan användas som cfFormat- medlem i en FORMATC- struktur.

 

Shell Urklippsformat ordnas här i tre grupper, baserat på hur de används.

Format för överföring av filsystemobjekt

Dessa format används för att överföra en eller flera filer eller andra Shell-objekt.

CF_HDROP

Det här Urklippsformatet används när du överför platserna för en grupp med befintliga filer. Till skillnad från de andra Shell-formaten är det fördefinierat, så du behöver inte anropa RegisterClipboardFormat. Data består av en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en DROPFILES- struktur som dess hGlobal medlem.

pFiles medlem i DROPFILES- struktur innehåller en förskjutning till en dubbel null--avslutad teckenmatris som innehåller filnamnen. Om du extraherar ett CF_HDROP format från ett dataobjekt kan du använda DragQueryFile för att extrahera enskilda filnamn från det globala minnesobjektet. Om du skapar ett CF_HDROP format som ska placeras i ett dataobjekt måste du skapa filnamnsmatrisen.

Filnamnsmatrisen består av en serie strängar som var och en innehåller en fils fullständigt kvalificerade sökväg, inklusive avslutande NULL- tecken. Ytterligare ett null- tecken läggs till i den sista strängen för att avsluta matrisen. Om filerna c:\temp1.txt och c:\temp2.txt överförs ser teckenmatrisen ut så här:

c:\temp1.txt'\0'c:\temp2.txt'\0''\0'

Not

I det här exemplet används \0 för att representera null- tecken, inte de literaltecken som ska ingå.

Om objektet kopierades till Urklipp som en del av en dra och släpp-åtgärd innehåller pt medlem i DROPFILES- struktur koordinaterna för den punkt där objektet togs bort. Du kan använda DragQueryPoint för att extrahera markörkoordinaterna.

Om det här formatet finns i ett dataobjekt simulerar en OLE-dra-loop WM_DROPFILES funktioner med icke-OLE-släppmål. Detta är viktigt om programmet är källan till en dra och släpp-åtgärd i ett Windows 3.1-system.

CFSTR_FILECONTENTS

Den här formatidentifieraren används med CFSTR_FILEDESCRIPTOR format för att överföra data som om det vore en fil, oavsett hur de faktiskt lagras. Data består av en STGMEDIUM- struktur som representerar innehållet i en fil. Filen representeras normalt som ett strömobjekt, vilket undviker att behöva placera innehållet i filen i minnet. I så fall är tymed medlem i STGMEDIUM- struktur inställd på TYMED_ISTREAM och filen representeras av ett IStream-gränssnitt. Filen kan också vara ett lagrings- eller globalt minnesobjekt (TYMED_ISTORAGE eller TYMED_HGLOBAL). Det associerade CFSTR_FILEDESCRIPTOR-formatet innehåller en FILEDESCRIPTOR- struktur för varje fil som anger filens namn och attribut.

Målet behandlar data som är associerade med ett CFSTR_FILECONTENTS format som om det vore en fil. När målet anropar IDataObject::GetData för att extrahera data, anger den en viss fil genom att ange lindex medlem i FORMATC struktur till det nollbaserade indexet för filens FILEDESCRIPTOR- struktur i det tillhörande CFSTR_FILEDESCRIPTOR formatet. Målet använder sedan den returnerade gränssnittspekaren eller det globala minneshandtaget för att extrahera data.

CFSTR_FILEDESCRIPTOR

Den här formatidentifieraren används med CFSTR_FILECONTENTS format för att överföra data som en grupp med filer. De här två formaten är det bästa sättet att överföra Shell-objekt som inte lagras som filsystemfiler. Dessa format kan till exempel användas för att överföra en grupp e-postmeddelanden som enskilda filer, även om varje e-post faktiskt lagras som ett datablock i en databas. Data består av en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en FILEGROUPDESCRIPTOR- struktur som följs av en matris som innehåller en FILEDESCRIPTOR- struktur för varje fil i gruppen. För varje FILEDESCRIPTOR- struktur finns det ett separat CFSTR_FILECONTENTS format som innehåller innehållet i filen. Om du vill identifiera en viss fils CFSTR_FILECONTENTS format anger du värdet lIndex för strukturen FORMATC till det nollbaserade indexet för filens FILEDESCRIPTOR- struktur.

Det CFSTR_FILEDESCRIPTOR formatet används ofta för att överföra data som om det vore en grupp med filer, oavsett hur de faktiskt lagras. Från målets perspektiv representerar varje CFSTR_FILECONTENTS format en enda fil och behandlas därefter. Källan kan dock lagra data på valfritt sätt. Även om ett CSFTR_FILECONTENTS format kan motsvara en enda fil, kan det till exempel även representera data som extraherats av källan från en databas eller ett textdokument.

CFSTR_FILENAME

Den här formatidentifieraren används för att överföra en enda fil. Data består av en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en enda null--avslutad sträng som innehåller filens fullständigt kvalificerade filsökväg. Det här formatet har ersatts av CF_HDROP, men det stöds för bakåtkompatibilitet med Windows 3.1-program.

CFSTR_FILENAMEMAP

Den här formatidentifieraren används när en grupp filer i CF_HDROP format byts namn och överförs. Data består av en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en dubbel null--avslutad teckenmatris. Den här matrisen innehåller ett nytt namn för varje fil, i samma ordning som filerna visas i tillhörande CF_HDROP format. Formatet för teckenmatrisen är detsamma som det som används av CF_HDROP för att visa en lista över de överförda filerna.

CFSTR_MOUNTEDVOLUME

Den här formatidentifieraren används för att överföra en sökväg på en monterad volym. Den liknar CF_HDROP, men den innehåller bara en enda sökväg och kan hantera de längre sökvägssträngar som kan behövas för att representera en sökväg när volymen monteras på en mapp. Data består av en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en enda null--avslutad sträng som innehåller den fullständigt kvalificerade filsökvägen. Sökvägssträngen måste sluta med ett \-tecken följt av avslutande NULL-.

Före Windows 2000 kunde volymer endast monteras på enhetsbeteckningar. För Windows 2000- och senare system med en NTFS-formaterad enhet kan du även montera volymer på tomma mappar. Den här funktionen gör att en volym kan monteras utan att ta upp en enhetsbeteckning. Den monterade volymen kan använda alla format som stöds, inklusive FAT, FAT32, NTFS och CDFS.

Du kan lägga till sidor i egenskapsbladet Enhetsegenskaper genom att implementera en egenskapsbladshanterare. Om volymen monteras på en enhetsbeteckning skickar Shell sökvägsinformation till hanteraren med CF_HDROP format. Med Windows 2000- och senare system används det CF_HDROP formatet när en volym monteras på en enhetsbeteckning, precis som med tidigare system. Men om en volym monteras på en mapp används CFSTR_MOUNTEDVOLUME formatidentifierare i stället för CF_HDROP.

Om endast enhetsbeteckningar används för att montera volymer används endast CF_HDROP och befintliga egenskapsbladshanterare fungerar som de gjorde med tidigare system. Men om du vill att hanteraren ska visa en sida för volymer som är monterade på mappar och enhetsbeteckningar måste hanteraren kunna förstå både CSFTR_MOUNTEDVOLUME- och CF_HDROP format.

CFSTR_SHELLIDLIST

Den här formatidentifieraren används när du överför platserna för ett eller flera befintliga namnområdesobjekt. Den används på ungefär samma sätt som CF_HDROP, men den innehåller PIDL:er i stället för filsystemsökvägar. Med hjälp av PIDL:er kan CFSTR_SHELLIDLIST format hantera virtuella objekt samt filsystemobjekt. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal medlem pekar på en CIDA- struktur.

aoffset medlem i CIDA- struktur är en matris som innehåller förskjutningar till början av ITEMIDLIST- struktur för varje PIDL som överförs. Om du vill extrahera en viss PIDL måste du först fastställa dess index. Lägg sedan till värdet aoffset som motsvarar indexet till adressen för CIDA- struktur.

Det första elementet i aoffset innehåller en förskjutning till den fullständigt kvalificerade PIDL:en för en överordnad mapp. Om den här PIDL:en är tom är den överordnade mappen skrivbordet. Vart och ett av de återstående elementen i matrisen innehåller en förskjutning till en av de PIDL:er som ska överföras. Alla dessa PIDL:er är relativa till PIDL för den överordnade mappen.

Följande två makron kan användas för att hämta PIN-adresser från en CIDA- struktur. Den första tar en pekare till strukturen och hämtar PIDL för den överordnade mappen. Den andra tar en pekare till strukturen och hämtar en av de andra PIDL:erna, som identifieras av dess nollbaserade index.

#define GetPIDLFolder(pida) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[0])

#define GetPIDLItem(pida, i) (LPCITEMIDLIST)(((LPBYTE)pida)+(pida)->aoffset[i+1])

Not

Värdet som returneras av dessa makron är en pekare till PIDL:s ITEMIDLIST- struktur. Eftersom dessa strukturer varierar i längd måste du bestämma slutet av strukturen genom att gå igenom var och en av ITEMIDLIST strukturens SHITEMID- strukturer tills du når NULL- som markerar slutet.

CFSTR_SHELLIDLISTOFFSET

Den här formatidentifieraren används med format som CF_HDROP, CFSTR_SHELLIDLISToch CFSTR_FILECONTENTS för att ange positionen för en grupp med objekt efter en överföring. Data består av en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en matris med POINT- strukturer. Den första strukturen anger skärmkoordinaterna, i bildpunkter, i det övre vänstra hörnet av rektangeln som omger gruppen. Resten av strukturerna anger platserna för de enskilda objekten i förhållande till gruppens position. De måste vara i samma ordning som de som används för att visa objekten i associerat format.

Format för överföring av virtuella objekt

Det CFSTR_SHELLIDLIST formatet kan användas för att överföra både filsystem och virtuella objekt. Det finns dock också flera specialiserade format för överföring av vissa typer av virtuella objekt.

CFSTR_NETRESOURCES

Den här formatidentifieraren används vid överföring av nätverksresurser, till exempel en domän eller server. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal medlem pekar på en NRESARRAY- struktur. nr medlem i den strukturen anger en NETRESOURCE- struktur vars lpRemoteName medlem innehåller en null--avslutad sträng som identifierar nätverksresursen. Släppmålet kan sedan använda data med någon av Windows-nätverk (WNet) API-funktioner, till exempel WNetAddConnection, för att utföra nätverksåtgärder på objektet.

CFSTR_PRINTERGROUP

Den här formatidentifieraren används vid överföring av egna namn på skrivare. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en sträng i samma format som den som används med CF_HDROP. Men pFiles medlem i DROPFILES- struktur innehåller ett eller flera egna namn på skrivare i stället för filsökvägar.

CFSTR_INETURL

Den här formatidentifieraren ersätter CFSTR_SHELLURL (inaktuell). Om du vill att programmet ska ändra Urklipps-URL:er använder du CFSTR_INETURL i stället för CFSTR_SHELLURL (inaktuell). Det här formatet ger den bästa Urklippsrepresentationen av en enda URL. Om UNICODE inte har definierats hämtar programmet den CF_TEXT/CFSTR_SHELLURL versionen av URL:en. Om UNICODE har definierats hämtar programmet den CF_UNICODE versionen av URL:en.

CFSTR_SHELLURL (inaktuell)

Not

Den här formatidentifieraren har föråldrats. använd CFSTR_INETURL i stället.

 

Format för kommunikation mellan källa och mål

Dessa formatidentifierare tillåter kommunikation mellan källa och mål. Formaten medföljer data och ger programmen större kontroll över flytt-kopiera-klistra in eller dra-och-släpp-åtgärder som involverar Shell-objekt.

CFSTR_INDRAGLOOP

Den här formatidentifieraren används av ett dataobjekt för att ange om det finns i en dra och släpp-loop. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på ett DWORD- värde. Om värdet för DWORD- inte är noll ligger dataobjektet i en dra och släpp-loop. Om värdet är inställt på noll ligger dataobjektet inte inom en dra och släpp-loop.

Vissa släppmål kan anropa IDataObject::GetData och försöka extrahera data medan objektet fortfarande finns i dra och släpp-loopen. Om objektet återges fullständigt för varje sådan förekomst kan det leda till att dramarkören stannar. Om dataobjektet stöder CFSTR_INDRAGLOOPkan målet i stället använda formatet för att kontrollera statusen för dra och släpp-loopen och undvika minnesintensiv återgivning av objektet tills det faktiskt tas bort. De format som är minnesintensiva att återge bör fortfarande ingå i FORMATC- uppräknare och i anrop till IDataObject::QueryGetData. Om dataobjektet inte anger CFSTR_INDRAGLOOP bör det fungera som om värdet är inställt på noll.

CFSTR_LOGICALPERFORMEDDROPEFFECT

version 5.0.Med den här formatidentifieraren kan en släppkälla anropa dataobjektets IDataObject::GetData-metod för att fastställa resultatet av en Shell-dataöverföring. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på ett DWORD som innehåller ett DROPEFFECT- värde.

Den CFSTR_PERFORMEDDROPEFFECT formatidentifieraren var avsedd att göra det möjligt för målet att ange för dataobjektet vilken åtgärd som faktiskt ägde rum. Shell använder dock optimerade flyttningar för filsystemobjekt när det är möjligt. I så fall anger Shell normalt värdet CFSTR_PERFORMEDDROPEFFECT till DROPEFFECT_NONE för att indikera för dataobjektet att de ursprungliga data har tagits bort. Källan kan därför inte använda värdet CFSTR_PERFORMEDDROPEFFECT för att avgöra vilken åtgärd som har ägt rum. De flesta källor behöver inte den här informationen, men det finns vissa undantag. Även om optimerade flyttningar till exempel eliminerar behovet av att en källa tar bort data, kan källan fortfarande behöva uppdatera en relaterad databas för att indikera att filerna har flyttats eller kopierats.

Om en källa behöver veta vilken åtgärd som utfördes kan den anropa dataobjektets IDataObject::GetData-metod och begära CFSTR_LOGICALPERFORMEDDROPEFFECT format. Det här formatet återspeglar i stort sett vad som händer från användarens synvinkel när åtgärden är klar. Om en ny fil skapas och den ursprungliga filen tas bort ser användaren en flyttåtgärd och formatets datavärde är inställt på DROPEFFECT_MOVE. Om den ursprungliga filen fortfarande finns där ser användaren en kopieringsåtgärd och formatets datavärde är inställt på DROPEFFECT_COPY. Om en länk har skapats blir formatets datavärde DROPEFFECT_LINK.

CFSTR_PASTESUCCEEDED

Den här formatidentifieraren används av målet för att informera dataobjektet, via dess IDataObject::SetData-metoden, att en delete-on-paste-åtgärd lyckades. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en DWORD- som innehåller ett DROPEFFECT- värde. Det här formatet används för att meddela dataobjektet att det ska slutföra klipp ut-åtgärden och ta bort ursprungliga data om det behövs. Mer information finns i Delete-on-Paste Operations.

CFSTR_PERFORMEDDROPEFFECT

Den här formatidentifieraren används av målet för att informera dataobjektet via dess IDataObject::SetData metod för resultatet av en dataöverföring. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på ett DWORD- inställt på lämpligt DROPEFFECT- värde, vanligtvis DROPEFFECT_MOVE eller DROPEFFECT_COPY.

Det här formatet används normalt när resultatet av en åtgärd kan antingen flyttas eller kopieras, till exempel i en optimerad flytt-- eller delete-on-paste-åtgärd. Det ger ett tillförlitligt sätt för målet att berätta för dataobjektet vad som faktiskt hände. Det introducerades eftersom värdet för pdwEffect som returnerades av DoDragDrop inte på ett tillförlitligt sätt angav vilken åtgärd som hade ägt rum. Det CFSTR_PERFORMEDDROPEFFECT formatet är det tillförlitliga sättet att indikera att en ooptimerad flytt har ägt rum.

CFSTR_PREFERREDDROPEFFECT

Den här formatidentifieraren används av källan för att ange om den önskade metoden för dataöverföring ska flyttas eller kopieras. Ett släppmål begär det här formatet genom att anropa dataobjektets IDataObject::GetData-metod. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på ett DWORD- värde. Det här värdet är inställt på DROPEFFECT_MOVE om en flyttåtgärd föredras eller DROPEFFECT_COPY om en kopieringsåtgärd föredras.

Den här funktionen används när en källa kan ha stöd för en flytt- eller kopieringsåtgärd. Den använder CFSTR_PREFERREDDROPEFFECT format för att kommunicera sin inställning till målet. Eftersom målet inte är skyldigt att uppfylla begäran måste målet anropa källans IDataObject::SetData-metod med ett CFSTR_PERFORMEDDROPEFFECT format för att tala om för dataobjektet vilken åtgärd som faktiskt utfördes.

Med en åtgärden delete-on-paste används CFSTR_PREFERREDDROPFORMAT-formatet för att tala om för målet om källan har klippt ut eller kopierat. Med en dra och släpp-åtgärd kan du använda CFSTR_PREFERREDDROPFORMAT för att ange shell-åtgärden. Om det här formatet inte finns utför Shell en standardåtgärd baserat på kontext. Om en användare till exempel drar en fil från en volym och släpper den på en annan volym är Shells standardåtgärd att kopiera filen. Genom att inkludera ett CFSTR_PREFERREDDROPFORMAT format i dataobjektet kan du åsidosätta standardåtgärden och uttryckligen be Shell att kopiera, flytta eller länka filen. Om användaren väljer att dra med höger knapp anger CFSTR_PREFERREDDROPFORMAT standardkommandot på dra och släpp snabbmenyn. Användaren kan fortfarande välja andra kommandon på menyn.

Före Microsoft Internet Explorer 4.0 angav ett program att det överförde genvägsfiltyper genom att ange FD_LINKUI i dwFlags medlem i FILEDESCRIPTOR- struktur. Målen var sedan tvungna att använda ett potentiellt tidskrävande anrop för att IDataObject::GetData för att ta reda på om flaggan FD_LINKUI har angetts. Det bästa sättet att ange att genvägar överförs är nu att använda det CFSTR_PREFERREDDROPEFFECT format som angetts till DROPEFFECT_LINK. För bakåtkompatibilitet med äldre system bör dock källor fortfarande ange flaggan FD_LINKUI.

CFSTR_TARGETCLSID

Den här formatidentifieraren används av ett mål för att tillhandahålla dess CLSID till källan. Data är en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal medlem pekar på CLSID GUID för släppmålet.

Det här formatet används främst för att tillåta att objekt tas bort genom att dra dem till papperskorgen. När ett objekt tas bort i papperskorgen anropas källans IDataObject::SetData-metod med ett CFSTR_TARGETCLSID format inställt på papperskorgens CLSID (CLSID_RecycleBin). Källan kan sedan ta bort det ursprungliga objektet.

CFSTR_UNTRUSTEDDRAGDROP

Den här formatidentifieraren används av Windows Internet Explorer och Windows Shell för att tillhandahålla en mekanism som du kan använda för att blockera eller fråga efter dra och släpp-åtgärder som kommer från Internet Explorer tillsammans med flaggan URLACTION_SHELL_ENHANCED_DRAGDROP_SECURITY.

CFSTR_UNTRUSTEDDRAGDROP läggs till av källan för en dra och släpp-åtgärd för att ange att dataobjektet kan innehålla opålitliga data. Data representeras av en STGMEDIUM- struktur som innehåller ett globalt minnesobjekt. Strukturens hGlobal- medlem pekar på en DWORD- inställd på en lämplig URL-åtgärd flagga för att orsaka en principkontroll via IInternetSecurityManager::P rocessUrlAction-metoden med hjälp av flaggan PUAF_ENFORCERESTRICTED.

DraWindow

Det här formatet används i en dra och släpp-åtgärd för att identifiera ett objekts dra-bild (fönster) så att dess visuella information kan uppdateras dynamiskt. När ett objekt dras över ett släppmål uppdaterar ett program sin DROPDESCRIPTION- struktur som svar på metoden IDropTarget::D ragOver eller IDropSource::GiveFeedback. DROPDESCRIPTION- uppdateras med ett nytt DROPIMAGETYPE- värde som anger dekorationen som ska tillämpas på dra-fönstrets visuella objekt. Till exempel en indikation på att filen kopieras i stället för att flyttas eller att objektet inte kan tas bort till den platsen. Men tills objektet tar emot ett DDWM_UPDATEWINDOW meddelande uppdateras inte de visuella objekten. Det här formatet innehåller HWND- för mottagardragfönstret till avsändaren av DDWM_UPDATEWINDOW-meddelandet.

Urklippsdata är av typen TYMED_HGLOBAL. Det är en DWORD- representation av en HWND-. Data kan skickas till funktionen ULongToHandle, definierad i Basetsd.h, för att tillhandahålla en 64-bitars HWND- för användning i 64-bitars Windows.

Det här formatet kräver inte att Shlobj.h inkluderas.